Hierarchy Bookmarks for VS Code

Hierarchy Bookmarks is a premium, lightweight, zero-dependency VS Code extension that lets you bookmark lines of code with custom, readable labels. Instantly organize and jump to bookmarked lines from a dedicated sidebar panel using a fully customizable nested tree structure with drag-and-drop support, and enjoy dynamic tracking that prevents bookmarks from drifting when you edit your code.

Features

• 🔖 Line Bookmarking: Toggle bookmarks on any line instantly using a keybinding, context menu, or command.
• 🏷️ Custom Labels: Give your bookmarks readable, clear descriptions (e.g. "Fix this loop bug", "API Entry Point") instead of just showing the filename and line number.
• 🧭 Display Bookmark Hierarchy: Bookmarks can be organized in a tree hierarchy. Click any bookmark to jump to its file and line.
• 🔀 Drag & Drop Reorganization: Drag and drop bookmarks to create nested hierarchies of any depth. Drag a bookmark onto another to nest it, or drop it between them to reorder.
• 🐛 Create Hierarchy from Debug Stack: Capture the active call stack when paused at a breakpoint and graft it into your bookmark tree to preserve debugging context.
• 📤 Export & Import: Save your bookmarks tree to a .json file and import it to merge bookmarks across workspaces or share with your team.

Detailed Usage Guides

1. Create Labeled Bookmarks

You can bookmark any line of code instantly to find it later.

• Toggle standard bookmark: Press Ctrl + Alt + B (or Cmd + Alt + B on Mac) to bookmark the current line. The line text is automatically used as the default label.
• Add custom label: Use the context menu (Right-click in the editor → Bookmarks: Add Bookmark with Label) or run it from the Command Palette to enter a custom label (e.g., TODO: Fix API loop).
• Edit/Delete: Hover over a bookmark in the sidebar and click the edit (✏️) or trash (🗑️) icon to rename or delete it.

2. Organize Bookmarks in a Hierarchy

You can structure your bookmarks into logical directories/groups to map out call chains, features, or modules.

• Drag & Drop: Simply drag a bookmark and drop it onto another in the sidebar to reorganize.
• Context-Aware Insertion:
  • If no bookmark is selected: Any new bookmark you add will be placed at the root level.
  • If a bookmark is selected: Adding a new bookmark (or dropping one) triggers a prompt allowing you to choose exactly where to place it relative to the selection:
    • Add Inside: Nest it as a child of the selected bookmark.
    • Add As Parent: Make the new bookmark a parent, moving the selected bookmark inside it.
    • Add Before / Add After: Place it as a sibling at the same level.
    • Add at Root Level: Add at the top level.

3. Create a Hierarchy from Debug Stack

When paused at a breakpoint during debugging, you can capture the active call stack as a nested hierarchy of bookmarks to preserve your debugging context.

• Run the command: Click the play/bug icon (visible on the Bookmarks sidebar title bar when debugging) or run Bookmarks: Add Bookmarks for Stack from the Command Palette.
• Context-Aware Suffix Grafting:
  • If no bookmark is selected (or no overlap is found): The extension captures the entire call stack (from the entry point down to the breakpoint line) and prompts you to place this new call tree.
  • If a bookmark is selected: The extension scans the call stack starting from the breakpoint (callee) up to the entry point (caller). If any stack frame matches a bookmark in the selected sub-tree, it halts the search and grafts only the active suffix (the frames called after that point) directly under the matching bookmark. For example, if you have A -> B -> C and select A, and hit a stack D -> B -> E -> F, it will graft E -> F directly under B.

4. Smart Bookmark Anchoring (Git Pull Resiliency)

Bookmarks shouldn't break when code is updated externally (e.g., via git pull or external editors).

• Automatic Alignment: When a file is opened, the extension checks if the text at the bookmarked line number matches the saved text snippet.
• Proximity Relocation: If the lines have shifted, the extension searches the entire file for the closest match of that exact line text and automatically re-anchors the bookmark to its new correct line number, updating the workspace state.
• Note: To prevent false positives, very short lines (fewer than 3 characters) or lines consisting only of code formatting symbols (like {, }, ()) are skipped from auto-shifting.

Keyboard Shortcuts

Interactive Controls

Sidebar Tree View

• Drag & Drop: Drag a bookmark and drop it onto another. An elegant prompt will let you choose to:
  • Add Inside: Make it a child of the target bookmark.
  • Move Before: Insert it immediately before the target bookmark (at the same level).
  • Move After: Insert it immediately after the target bookmark (at the same level).
  • Note: Dropping on empty space moves the bookmark back to the root level. Built-in checks prevent cycle nesting.
• Click: Opens the file and scrolls to the bookmarked line.
• Hover: Shows a tooltip preview of the file path and the bookmarked line's code snippet.
• Hover inline actions:
  • ✏️ Edit Bookmark Label: Rename your bookmark.
  • 🗑️ Delete Bookmark: Delete individual bookmarks (and any of their nested children).
• Right-Click Menu: Access commands to edit or delete.
• View Header Actions (Top-Right):
  • 🔄 Refresh Bookmarks: Force refresh the list.
  • 🧹 Clear All Bookmarks: Confirm and delete all bookmarks in the workspace.
  • 📤 Export Bookmarks to File: Save current bookmarks tree as a .json file.
  • 📥 Import Bookmarks from File: Select a .json file to merge its bookmarks with your current workspace tree.

Development & Debugging

Since this extension has no compile step and no external npm dependencies, you can run and debug it instantly in VS Code.

How to Run

1. Open this folder (hierarchy-bookmarks) in a new VS Code window.
2. Open extension.js or press Ctrl+Shift+D to go to the Run and Debug side menu.
3. Click the Run Extension green play button (or press F5).
4. A new window ([Extension Development Host]) will open.
5. In the new window, open any codebase/folder, open a file, and press Ctrl+Alt+B (or Cmd+Alt+B on Mac) to start bookmarking!