Branchline Notes

A local-first VS Code outliner inspired by Logseq and Workflowy-style navigation. One root Markdown file connects all your notes. Documents appear as expandable nodes, so you can work across files without leaving the outline.

Install and open

1. Run Extensions: Install from VSIX… in the VS Code Command Palette and choose branchline-notes-0.4.2.vsix.
2. Open a workspace folder.
3. Run Branchline Notes: Open Outliner, or click the Branchline Notes activity bar icon.

The extension's identity is now martincodes.branchline-notes. If you installed an earlier Branchline or Branchline Outliner development package, uninstall that old extension before installing this one to avoid duplicate commands. Your Markdown files stay in place.

The extension creates outliner.md in the first workspace folder if it does not exist. To anchor your outline to another existing file, run Branchline Notes: Choose Root Markdown File. You can also set branchline.rootFile before opening a notebook. Without a workspace, notes use VS Code's extension storage directory.

Concepts and descriptions

Write a bullet as Concept name -- description to display Concept name — description, with both parts flowing inline at the same text size. Markdown formatting works in either part. Click to edit the original -- syntax; saved Markdown stays unchanged.

The first spaced -- on the first line is the separator. Descriptions can continue on later lines and include code, tables, or images. Delimiters inside code, links, references, and tables remain literal. Ordinary bullets keep their existing rendering.

Block references show only the concept name, including its formatting. Page references do the same when the page title uses this syntax. Lookup and Ctrl+Alt+P still search descriptions, and references retain their original targets when descriptions change.

Build branchline-notes-0.4.2.vsix with npm run package.

One outline, many documents

The top toolbar, footer, and surrounding canvas share one background from your VS Code theme. Accents use the theme's link color. The note body has a distinct bordered surface: darker in dark themes, lighter in light themes, with matching inline editors and focused bullets. Hovering, editing, or selecting an item does not add a background fill; text color and keyboard focus outlines provide feedback. High-contrast themes retain their native surfaces and contrast borders.

The header has All notes, Tasks, and Daily notes buttons, each with an icon and label. There is no left panel in the editor. Open the … Notebook menu in the header for search across all notes, Pages, tags, New document, and Add Markdown file.

Breadcrumbs sit just above the note viewport. Click a page or parent bullet in the path to navigate back up the outline.

Formatted titles and references display bold, italic, strikethrough, and inline code without their Markdown markers. References flow within sentences and wrap with the text. Click a formatted title to edit its Markdown, then press Escape or click away to return to the rendered title.

References and backlinks appear in an attached panel beneath the note, with a theme-colored background and vertical accent rails. The note keeps 12px rounded top corners, and the attached panel has matching rounded bottom corners with a flush join between them. Without references, all four note corners are rounded. Backlinks show their source document and a formatted preview.

• Click a bullet dot to drill into that node. Breadcrumbs take you back out.
• Mounted Markdown files always open in Markdown document view, whether reached through their dot, a reference, search, breadcrumbs, or navigation history. Ordinary bullets open in Focus view.
• Use chevrons to collapse and expand branches, or the toolbar to collapse/expand all. Expanded branches show a plain dot; a ring marks a collapsed branch with hidden children.
• Drag a bullet dot to move the bullet and its entire subtree. Drop near a row's top or bottom edge to place it before or after that row; drop in the middle to nest it. A line or dashed outline marks the destination. Drag toward the viewer's top/bottom edge to scroll. Drop into a document node to move content into its Markdown file, including empty files. Use Undo/Redo to reverse a move. Branches cannot be dropped into themselves or their descendants.
• Type Project notes /document in a bullet and press Enter. Branchline Notes creates .outliner/documents/Project notes.md, moves the bullet's children into that file, and mounts the file under the original bullet. Its descendants stay editable inline.
• Use Add Markdown file to mount one or more existing .md, .markdown, or .mdown files. Imported files stay in their original locations. Editing their nodes updates those files.
• To remove a file from the outline, use its × action in Pages or the document toolbar, or the trash action on its document node or focused heading. The source Markdown file stays on disk and can be added again. Nested documents and their tasks leave the notebook if no other mount still reaches them; shared mounts remain available. Row delete controls have their own space beside the text, including while editing.
• Pages in the Notebook menu lists the root and linked documents. All notes shows their connected outline.
• Create a task with Add task, /task, or Ctrl+Enter (Cmd+Enter on macOS). The Tasks view contains unfinished tasks grouped by source document, including tasks in collapsed branches.
• Type #tags to organize notes; click a tag to find matching bullets across files.
• Type [[ to open a lookup for blocks and pages across the connected notebook, including daily notes. Results show the owning page and prioritize the current file. Filter by bullet text or page name/date, use ↑/↓, and press Enter or Tab to insert the selected reference. Clicking a reference navigates to its target. Clicking or focusing a bullet with references displays previews below the document viewer. Focusing a target also shows the blocks that reference it in that section.

Slash commands

Type / at the start of a bullet or after a space to open the command menu. Keep typing to filter, then select with ↑/↓ and Enter/Tab or click an item. Escape closes the menu. Commands work in inline editors and focused headings; paths, URLs, and code remain literal.

These commands replace the task, code, and document action icons beside each row. The trash button remains available without covering the note text.

Display size

Open Aa in the top-right corner to adjust the interface from 100% to 200%. Enable Wide document view to use the available width on larger monitors. Reset restores 100% and the standard document width. These preferences are saved across sessions and workspaces. Chevron icons are smaller while keeping their click targets easy to use.

Bullets use compact spacing, with tighter multiline text and vertical guides connecting nested branches. Guides follow expanded branches through multiline content and mounted documents. Hovering or selecting a bullet does not add a background fill.

View history

Use the mouse Back and Forward buttons, the arrows at the top left, or Alt+Left / Alt+Right to revisit pages, focused bullets, tasks, tags, and search results. History restores the search query and scroll position. Opening a different destination clears the forward history; editing text and expanding bullets do not add history entries. History is scoped to the current open Branchline view.

Document links are ordinary relative Markdown links with an explicit marker:

- [Project notes](<.outliner/documents/Project%20notes.md>) <!-- branchline:document -->

Only marked links are mounted. Ordinary Markdown links remain ordinary text. Circular and missing links are not expanded. Removing a document node detaches that occurrence; it never deletes the file. Indenting a sibling into a document anchor is blocked to prevent silently moving content between files. Focus the document first to add content inside it.

Multiline bullets and code

Use Shift+Enter for a new line inside the same bullet, or paste multiline text. Blank lines and fenced code stay inside that bullet when saved and reopened. Typing three backticks on an empty line automatically inserts the closing fence and places the caret on the blank code line. This works in both inline bullets and focused headings. You can add a language name on the opening line, use /code, or paste a complete fence. Closing fences and backticks inside code are not auto-expanded.

Inside an open fence, Enter adds a code line and preserves indentation; Tab / Shift+Tab indent or outdent the current code line. Enter after the closing fence creates the next bullet. Code renders in a separate monospaced panel; literal [[references]], tags, and bullet-looking lines inside it stay code.

Tables

Paste or type a pipe table inside a bullet, then press Escape or click outside the editor to render it. Use Shift+Enter to add lines while editing Markdown, or type /table and press Enter to insert a two-column starter table with the first header selected.

- Observations

  | Object | Status | Mass |
  | :--- | :---: | ---: |
  | Disk A | **Ready** | 42 |
  | Disk B | [Paper](https://example.com) | 7 |

Hover over the rendered table to reveal + controls along its top and left edges. The top controls insert a column at that boundary; the left controls insert a data row below the header or an existing row. Controls also work with Tab and Enter. Click cell text or Edit table Markdown to change its content. Structural changes save immediately and support Undo/Redo.

Tables support left/center/right column alignment, existing inline formatting, links, images, and [[references]]. Escape a literal pipe as \|. Tables in fenced code remain literal. Tables render in focused views, search results, and reference previews; insertion controls appear in the editable outline and focused view. Large outlines reserve space for table rows and provide a scrollable preview for tall or wide tables.

Block and page references

The [[ lookup searches all connected Markdown pages and daily notes, including collapsed blocks. It offers local blocks first and shows page names and ancestor context so similarly named bullets can be distinguished. A diary bullet can link to another page's block, and other pages can link back to diary blocks. Page references retain the [[Page name]] syntax; clicking a missing page reference offers to create it. Outgoing previews, block backlinks, and page backlinks appear below the note body.

Block references display the target's current first line and keep working when the target is renamed, reordered, or moved into a linked document. When a block is first referenced, its Markdown receives a small persistent branchline:block ID comment. References use [[#^ID|Label]] in the source. IDs are hidden in the rendered view; click the focused heading to edit its source text. A deleted or detached target is shown as unavailable rather than opening a different block.

Clickable links

Markdown links, plain https:// / http:// URLs, www. addresses, and angle-bracket autolinks render as clickable links throughout the outline, focused headings, and reference previews. Click a link or focus it with Tab and press Enter. Opening a link leaves the bullet out of edit mode; click its surrounding text to edit the Markdown.

- [Documentation](https://code.visualstudio.com/docs "Optional title")
- Visit https://example.com or <https://example.com/help>
- [Email](mailto:person@example.com)
- [Related file](<notes/my file.md>)
- [![Preview](assets/diagram.png)](https://example.com/diagram)

Web links open through VS Code in your default browser; mailto: links use your mail application. File links open in VS Code and resolve relative to the Markdown file that owns the bullet. Relative file destinations are preserved when moving a bullet between documents or using /document. Links inside code stay literal, and script/command destinations remain plain text. The [[page or block]] reference syntax continues to navigate within Branchline Notes.

Inline images

Use standard Markdown image syntax in a bullet:

- A diagram ![Project diagram](assets/diagram.png)
- A path with spaces ![Sketch](<assets/my sketch.png> "Optional title")
- A remote image ![Photo](https://example.com/photo.jpg)

Relative paths resolve from the Markdown file that owns the bullet, including mounted documents and daily notes. Local resources must be within the workspace/root directory or a mounted file's directory. HTTPS images and embedded data:image/... images are also supported. Images appear in the outline, focused view, and reference previews; large virtualized outlines show thumbnails. Missing images show a readable placeholder, and image syntax inside code stays literal. Relative image links are updated when moving bullets between documents or converting a branch with /document.

Find across your notebook

Press Ctrl+Alt+P (Cmd+Alt+P on macOS), click Find in notes, or run Branchline Notes: Find in Notes from the normal Ctrl+Shift+P Command Palette.

The native quick picker searches every node in the root outline and all connected Markdown documents, including nested documents and daily notes, regardless of the current view. Each result shows its document name, file path, and parent context. Enter multiple words in any order; choosing a result opens that document and focuses the matching node. Detached files are excluded.

The picker returns up to 200 matches at a time. Narrow the query for more specific results. Multiline text and code within a bullet are searchable as that bullet; bullet-looking lines inside code do not become independent results. The normal VS Code Command Palette shortcut is unchanged.

Daily notes

Click Daily notes, use Ctrl+Alt+D (Cmd+Alt+D on macOS), or run Branchline Notes: Open Today's Daily Note.

Daily notes appear in the root as:

Daily
  2026
    November
      Nov 9–15
        Wednesday, Nov 11

Each day is a real file in .outliner/daily/YYYY/YYYY-MM-DD.md. Weeks start Monday; the date uses your computer's local timezone. Reopening today focuses the existing note. Small branchline:daily comments identify calendar nodes in the root file.

Editing shortcuts

Storage and large files

Markdown files are the source of truth. There is no database, account, server, or network dependency. Unchanged imported files are not rewritten. The parser preserves original Markdown chunks, including headings, paragraphs, fences, tables, blank lines, and line endings. Changed outline rows use canonical Markdown formatting. Code uses safe text rendering in monospaced panels; embedded HTML is not executed.

Text saves wait until you stop typing for 750 milliseconds. The status bar shows Waiting to save… during that pause. Pending edits flush immediately when you leave the editor, press Ctrl+S / Cmd+S, perform a structural action, or close the view. The extension host holds the latest draft while waiting, and coalesces each typing burst into one save instead of reading and writing Markdown files on every keystroke.

Writes use a temporary file and rename, with one previous version saved alongside the source as filename.md.branchline.bak. You may want to ignore *.branchline.bak in Git. Unsaved source-editor changes and conflicting disk edits block outline writes instead of being overwritten. The error banner lets you export the current draft. Save or export your draft before reloading to resolve a conflict.

Export produces a standalone Markdown outline of the current view, expanding linked document contents so the exported draft includes the notes you can see.

Saved source edits are refreshed in the outliner. Files beneath the root directory are watched for external filesystem changes; other mounted files refresh when saved in VS Code. Collapse state is kept in VS Code's workspace state. Source-line IDs are rebuilt after an external reload, so focused-node navigation may reset after structural edits outside the outliner.

Outlines with more than 300 visible rows use a virtual list with single-line previews and taller, scrollable previews for tables; editing exposes the full bullet text. The native finder is tested with 50,000 bullets, and browser integration tests import and navigate a 12,000-bullet document. Notebook validation currently allows 100,000 nodes and 1,000 linked files. Undo history is session-local and resets when documents are created/imported/detached or externally reloaded. This version does not support simultaneous collaborative editing of the same files.

Develop and verify

Requires Node.js 20+ and VS Code 1.95+.

npm install
npm run typecheck
npm run build
npm test
npm run test:ui
npm run test:host
npm run package

Press F5 to launch an Extension Development Host. npm run watch rebuilds scripts and styles. The UI integration test uses installed Microsoft Edge in headless mode, real filesystem operations in a temporary test workspace, and the actual extension/webview code with a mocked VS Code shell. It does not claim to replace testing in a real VS Code Extension Host.

npm run test:host launches an isolated VS Code profile and workspace for a native smoke test. On Windows it uses the standard per-user VS Code installation; set VSCODE_EXECUTABLE for a different installation. The browser suite verifies multiline/fenced editing, reference lookup and previews, reference persistence after source edits, and file detachment/reattachment in addition to the original outlining features.

Architecture: src/model.ts handles outline operations; src/moves.ts validates and relocates branches; src/markdown.ts parses, serializes, and indexes Markdown; src/storage.ts mounts and saves documents; src/extension.ts integrates VS Code; src/webview/ contains the editor.

Marketplace identity

Display name: Branchline Notes. Extension name: branchline-notes. Author and publisher: martincodes. Marketplace extension ID: martincodes.branchline-notes.

npm run package builds the distributable VSIX. Publish it through your registered martincodes publisher using the VS Code publishing workflow. Packaging does not publish the extension or register a publisher account.

VS Code integration follows the official Webview API and Tree View API guidance. Webviews use a strict content security policy and render note content as text.