The Bookmarks extension allows you to keep track of files and file locations. This allows you to leave breadcrumbs as you debug or navigate your code, or when saving all opened editors, it helps you to quickly switch between tasks.
- Bookmarks can be saved per-workspace or be global.
- Bookmarks can be organized using folders.
- Bookmarks can be managed via commands, and UI controls and gestures (e.g. drag-and-drop).
A bookmark is a reference to a document that is saved in the context of the current workspace (Workspace), or independent from it (Global). Absolute URIs are used as location descriptors, so any file system supported by VS Code can be bookmarked.
The UI, however, will adjust how bookmarks are displayed, e.g., calculating a relative path based on the current workspace.
A bookmark's identity is tied to its URL, which always includes a one-based line number fragment (e.g., file://workspace/file.rb#L1).
A folder is a container for bookmarks. As such, they are not related to the associated file-system structure.
The only constraint imposed by folders is that a given bookmark must be unique within it. For example, you can add a bookmark to file://workspace/file.rb#L1 to every single folder, but only once per folder. Every bookmark is its own entity, so if you change the display name of one of them, only the specific bookmark is updated.
The Bookmarks View is the main UI component for this extension. Bookmarks are split into two categories:
Global: shows bookmarks that are always available, regardless of what the current workspace is.Workspace: shows bookmarks associated with the currently open workspace, if any.
You can change the display mode of the tree:
Name: shows the file name and target line number. A path hint is shown as description.Path: shows the file path relative to the currently open workspace. The associated line number is shown as description.
There are two commands available to add a bookmark: Bookmarks: Bookmark Editor (Global) and Bookmarks: Bookmark Editor (Workspace). Both work on the currently active editor and add a bookmark under the appropriate category.
When a bookmark is created via any of these commands, the current line information is captured.
The following commands are available for other extensions to use: bookmarks.addBookmark.global and bookmarks.addBookmark.workspace. They take a single argument that is the path or URI to the file to bookmark.
Line information can be added by appending a fragment to the URI in the format: L<lineNumber>, with lineNumber being a 1-based index.
Editors can be dragged onto the tree, and they will be bookmarked. Additionally, it is also possible to drag items between categories to move them around. When a bookmark is created this way, the current line information is not captured.
There is a + button available on every category node (Global, Workspace) that bookmarks the currently active editor.
There are two commands available: Bookmarks: Remove All (Global) and Bookmarks: Remove All (Workspace).
The following commands are available for other extensions to use:
bookmarks.removeBookmark.globalandbookmarks.removeBookmark.workspace. They take a single argument that is the path or URI to the file to remove.bookmarks.removeBookmarks.globalandbookmarks.removeBookmarks.workspace. They take no argument and remove all bookmarks from the corresponding category.
There is an X button next to each bookmark, as well as one per category and one on the tree view header, that allow you to remove all bookmarks under the selected parent. Additionally, there is a Remove All action in the context menu for each of the category nodes.
Assigning a custom display name to a bookmark affects how it is presented in the UI. This can be used to provide a meaningful name, such as Bug Location.
In the Display Name context menu for a given bookmark, use:
Update…to update the display name.Removeto remove any custom display name.
Updating the line number helps keeping bookmarks in-sync with changes to their targets or to fix an incorrect value. The benefit here will improve as bookmarks evolve and carry more metadata so editing this value is easier than just recreating the bookmark.
In the Line Number context menu for a given bookmark, use:
Update…to update the line number.
Attach text notes to a bookmark for reference. Text is displayed on the the bookmark's tooltip.
In the Notes context menu for a given bookmark, use:
Update…to update the display name.Removeto remove any custom display name.
There are two commands, Bookmarks: Go to Next in Current Editor and Bookmarks: Go to Previous in Current Editor, that can be used to jump between bookmarks set in the current editor.
The following commands are available for other extensions to use: bookmarks.navigate.next.editor and bookmarks.navigate.previous.editor. They take a single optional argument, that is the path or URI to the file to navigate (it will be opened if needed).
Bookmarks are expected to be rendered as markers on the corresponding editor gutter. This is support via the Bookmarks: Toggle In-Editor Markers command but it is disabled by default due to VSCode #5923 which causes these markers to cover the breakpoint ones (unacceptable experience).
You can also use the Hide In-Editor Markers and Show In-Editor Markers actions in the Bookmarks view menu.
