Nestline — Native Outliner
Nestline turns .outline files into a keyboard-driven outliner for notes, tasks, and connected ideas. It uses the real VS Code text editor: normal selection, undo/redo, search, split editors, source control and accessibility stay available. Requires VS Code 1.100 or newer.
- A project #ideas
- [ ] Something to do
- [x] Something finished
- An idea with children
- A smaller idea
Indentation defines the hierarchy. Two spaces are the default; tabs and other configured tab sizes work too. Bullets can be -, * or +. Plain indented text is also accepted. Items support Markdown quotes, fenced blocks, hyperlinks, bold text, inline code and tags. Open examples/Features.outline for an interactive sample.
The editor displays all list markers as the same • dot in the normal text color, without link underlines. Bullet glyphs use 50% opacity, while the current item's glyph uses 100% opacity, following the caret in the active editor. This dims only the markers, not the item text. Saved text and clipboard contents keep the original marker. Click a glyph to focus its branch. Set outline.renderBulletGlyph to false to show plain markers with the same dimming behavior. Folding arrows appear when you hover over the folding gutter, including collapsed arrows. Collapsed items have no folding background by default; their clickable expansion dots use the theme's task-success color (testing.iconPassed). An editor-scoped decoration styles VS Code's native fold controls without changing installed VS Code files or other languages. This override depends on VS Code's native folding CSS classes. Fenced code remains literal. Wrapped lines use a hanging indent, aligned with item text at the default two-space indentation; VS Code's screen-reader mode overrides wrapped indentation.
Rich content and tasks
- Plain text and [a hyperlink](https://example.com)
- > A quote
> Another line of the same quote
- Code attached to this item
~~~javascript
console.log("Hello");
~~~
- [ ] To do
- [/] In progress
- [c] Cancelled
- [x] Done
Quote continuations and fenced blocks belong to their item and travel with it. Enter continues a quote; Enter on an empty continuation starts a sibling. Enter within a fence inserts a code line. Enter after its closing fence creates a sibling. Typing an opening fence and pressing Enter adds its closing fence. The Insert Fenced Code Block command adds a block to the current item. Backtick and tilde fences are supported; fenced contents do not become outline items or references. Hyperlinks use native VS Code link navigation.
Fenced code uses the editor's normal background. A language label such as sql, python/py, javascript/js, typescript/ts, json, yaml, or bash enables native syntax colors from your editor theme. Both fence styles support 39 common languages, with case-insensitive labels. Unknown or unlabeled fences remain plain text. See examples/Code.outline for samples.
Ctrl+Alt+Enter cycles through [ ] → [/] → [c] → [x] → [ ]. Set Task State… in the command palette or context menu chooses a state directly. Ctrl+Enter still toggles done/to do. Cancelled tasks are excluded from the active task total.
The Outline side panel has two sections. Outline Files, above Tasks, lists every .outline file in the workspace, including empty files and files without tasks. Click a file to open its full outline. Folder paths distinguish matching filenames, and the list follows file creation, deletion, and renaming. Use the New Outline button in the section header to choose a filename and create a saved .outline file with a starting bullet. In a workspace with multiple roots, creation uses the current outline's workspace folder or asks which folder to use. Without a workspace, New Outline opens an untitled outline.
The Tasks section scans all .outline files under every open workspace folder, including nested folders and files that are not open in an editor. It lists only task items, including completed and cancelled tasks, and shows each task's source file. Both sections skip .git, node_modules, and .dev directories. Without a workspace folder, Tasks tracks the active outline. Use its Group By… toolbar button to choose:
- Parent Bullet (default): group tasks by their immediate parent. Tasks without a parent appear under Top-level tasks.
- Task Status: group tasks under To do, In progress, Cancelled, or Done. Empty groups are hidden.
- None: show a flat list ordered by file and then by position in the document, including nested tasks once each.
The choice is saved for the workspace and can also be set with outline.taskGroupBy (parent, status, or none). Click a task or parent heading to open its source outline at that item, use the checkmark to toggle completion, or right-click a task to choose its state. Parents with the same name in different files stay separate; status groups combine tasks across files. Status headings expand or collapse their groups. The panel updates for unsaved edits and file creation, changes, and deletion. Focused views contribute their source outline's tasks once, including hidden branches.
File links
Use Outline: Insert File Link… from the command palette or editor context menu to choose a file. Nestline inserts a Markdown link with the filename as its label, or uses selected text in the bullet as the label. The linked file stays in its original location.
Type () in a bullet to open a searchable list of workspace files. VS Code's automatic closing parenthesis also triggers it. Search by filename or folder path, then press Enter to replace the pair with a file link. Typing [label]() keeps your label and fills in the destination; []() uses the filename. Escape closes the picker without changing the parentheses.
The picker searches all file types across the workspace roots, skipping .git, node_modules, and .dev. The folder button lets you browse outside the workspace. Insert File Link… uses this picker too; without a workspace, that command opens the regular file browser. Automatic picking ignores inline code, fenced code, escaped parentheses, undo/redo, and multiple cursors. Set outline.fileLinkPickerOnParentheses to false to disable the typing shortcut.
You can also type links directly:
- [Source code](../src/app.js)
- [Project notes](<docs/project notes.md>)
- [Local file](<C:/Users/me/Documents/notes.txt>)
- [File URI](file:///C:/Users/me/Documents/notes.txt)
Ctrl+click a link (Cmd+click on macOS, or your configured VS Code link modifier) to open it in VS Code. Text files open in the editor; other file types use their available VS Code editor or preview. Relative paths resolve beside the saved source outline, including in focused views. Absolute paths, Windows paths, UNC paths, file URIs, and percent-encoded spaces are supported. Use angle brackets around manually typed paths with spaces, and %23 for a literal # in a filename. The file picker handles encoding automatically and prefers portable relative links; untitled outlines and files on another drive use absolute URIs. Manually typed relative links in untitled outlines resolve from the first workspace folder. Links inside inline code and fenced blocks stay literal. See examples/Links.outline for working samples.
Workspace and scoped search
Press Ctrl+Shift+O (Cmd+Shift+O on macOS) in an outline editor or the Tasks panel to search all workspace .outline files, including unopened files and current unsaved edits. The Tasks panel's search button and Outline: Search Outline Items command open the same search. Without a workspace folder, search uses the current outline.
Search matches bullet text, ignoring case. Use > to narrow the search to descendants of matching bullets:
| Query |
Results |
performance |
All bullets containing “performance” |
IOMETE > performance |
Bullets containing “performance” underneath any bullet containing “IOMETE” |
IOMETE > performance > caching |
Bullets containing “caching” underneath those matching performance branches |
IOMETE > |
All descendants of matching IOMETE bullets |
Each scope searches descendants at any depth and stays within its branch and file. Multiple matching parent branches are searched together; overlapping branches do not duplicate results. Terms containing spaces match as phrases. Use \> to search for a literal greater-than sign. Results show their source file, parent path, and line number. Press Enter to jump to the item; Escape closes search without moving the editor. The workspace scan uses the same directory exclusions as the Tasks panel.
Images
Paste a copied image or screenshot with Ctrl+V (Cmd+V on macOS). Nestline saves the image with a unique filename in the workspace root and inserts its Markdown image link at the cursor. In a multi-folder workspace, it uses the folder containing the source outline. New folders are created when the paste is applied.
Set Outline: Image Paste Folder (outline.imagePasteFolder) to choose another destination:
"outline.imagePasteFolder": "assets/images"
Relative paths are based on the workspace root; absolute folder paths are also supported. Leave the setting empty to use the root. Without an open workspace, images go beside the saved outline unless an absolute destination is configured. Save an untitled outline or open a workspace before pasting if no absolute destination is set. Links resolve from the original outline even in a focused view. Pasting image files supports the same formats and 8 MB limit as previews. Use Paste As → Save Image and Insert Outline Link if another paste action is selected.
Use Markdown image syntax in a bullet:
- 
- 
- 
Nestline shows a thumbnail after the image link. Hover over the link or thumbnail for a larger preview. Set Outline: Image Max Size (outline.imageMaxSize, default 480 pixels) to limit the longest edge while keeping the aspect ratio. Small images are never enlarged; inline thumbnails also fit within the editor's line height. The native editor does not reserve full-height blocks between text lines.
Relative paths resolve from the saved source outline, including in focused views. Absolute file paths, HTTP(S) URLs, and base64 image data URLs are also supported. PNG, JPEG, GIF, WebP, and SVG previews support files up to 8 MB. Remote images load only in trusted workspaces. Images inside inline code or fences stay literal. Set outline.imagePreviews to false to disable previews. See examples/Images.outline for a sample.
References and backlinks
Type @ and start searching for another item in the same outline. Choose it with Enter or Tab. The completion inserts a readable reference and, on its first use, gives the destination a persistent identity:
- A shared idea ^o-1234567890
- Related thought @[A shared idea](#o-1234567890)
The identity keeps the link working when the destination is renamed or moved. The reference label records the text at insertion time; F12 and hover resolve the current destination. Identities are ordinary text, dimmed in the editor, so references survive saving, reopening and moving files. Keep the ^id token when editing a referenced item. You may also give an item a readable identity such as ^project-plan.
Only items with incoming references show a number on the right. Ctrl+click that number (Cmd+click on macOS, or your configured VS Code link modifier) opens the native Peek References panel. Shift+F12 and Outline: Peek Incoming References also open reference lookup. F12 on a reference jumps to its destination. The numbers count reference occurrences, not descendants. Duplicate branches receive new IDs and their copied internal references follow the copied targets. Broken references and duplicate IDs are marked in Problems. Reference syntax in inline or fenced code stays literal.
Fade and bullet focus
One attention button in the editor title bar controls dimming. Its icon shows the selected fade scope:
- None removes dimming.
- Bullet keeps the current item and its attached quotes and code bright, dimming other items.
- Children keeps the current item and all descendants bright, dimming other branches.
Fading follows the cursor. Set outline.fadeOpacity to adjust the opacity (default 0.25). The command palette also offers Outline: Choose Fade Scope….
To focus a branch, left-click its bullet glyph, or place the cursor anywhere in the item and press Alt+Right. This opens an editable native view of that item and its children in the current editor group. Dragging a text selection does not trigger drill-down. Ctrl+click remains available using VS Code's native link modifier. Code inside fences stays literal; keyboard focus from a quote or code line selects its owning item. Right-click a bullet for branch actions, task state, child insertion, duplication, and deletion.
Focus another child to go deeper. Focusing from the source again reuses its existing focus view. Closing that view stops background updates to it. Alt+Left expands to the focused branch's parent, then returns to the full outline at the root. Outline: Show Full Outline in the context menu or command palette returns immediately. You can also navigate through the Outline sidebar. The fade button works independently inside a focused branch; choosing None only clears dimming.
Focused edits update the original document's buffer. Save writes the entire source outline; changing focus does not save it. Structural shortcuts still move, indent, or complete the real branch. References search the full source and include incoming references from hidden items. A focused view stays on its branch while you edit its children. Unsaved outlines can be focused; save the original outline to a file before saving its focused view.
In a focused view, use Ctrl+Z / Ctrl+Y (macOS Cmd+Z / Cmd+Shift+Z) or the Undo/Redo in Source Outline context-menu commands. These operate on the source history, including hidden items. VS Code's general Edit-menu Undo/Redo operates on the scoped view's buffer, so use the source-aware commands for branch operations. The source tab retains its normal undo history after leaving focus.
Open examples/Focus.outline to try fading and branch navigation.
Development hosts keep recovery copies of dirty outline buffers in .dev/unsaved/. Save your work before reloading the entire developer window; runtime code reloads preserve the editor buffers.
Run it live
Requires Node.js and an installed desktop VS Code. There are no npm dependencies or build steps.
npm run dev
This opens an Extension Development Host with examples/Welcome.outline, using an isolated profile under .dev/development. It does not install the extension into your normal VS Code profile. Set VSCODE_EXECUTABLE to the VS Code executable path if it is installed somewhere unusual.
Save an implementation file in src/ and the running development extension reloads automatically, preserving open documents and unsaved edits. The Outline output channel reports reloads and errors. Outline: Reload Extension Code triggers a manual reload. Changes to package.json, grammar, language configuration or src/extension.js need Developer: Reload Window. You can also open this project in VS Code and press F5 to debug it.
Keyboard controls
All overrides apply only to .outline editors. Use Cmd instead of Ctrl on macOS.
| Key |
Action |
| Enter |
Insert a first child when children are visible; otherwise split / insert a sibling |
| Ctrl+A |
Select bullet text → its branch → each parent branch → the entire document |
| Ctrl+Shift+Enter |
Insert first child |
| Tab / Shift+Tab |
Indent / outdent the item and its descendants |
| Alt+Up / Alt+Down |
Move the entire branch among its siblings |
| Ctrl+Enter |
Complete / reopen the selected item(s) |
| Ctrl+Alt+Enter |
Cycle to do / in progress / cancelled / done |
| Alt+Enter |
Add / remove checkbox |
| Shift+Alt+Down |
Duplicate branch |
| Ctrl+Alt+Space |
Fold / unfold branch |
| Ctrl+Shift+O |
Search all workspace outlines; use parent > term to narrow to matching branches |
| Alt+Right |
Focus the current item and its children |
| Alt+Left |
Zoom out to the parent while focused; otherwise jump to parent |
| Backspace at item text start |
Outdent, or remove a root bullet |
| Backspace on an empty bullet |
Delete its line, preserving and promoting any children |
| Home |
Move directly to the item's text start, without bouncing through the marker |
Enter on an empty nested item outdents it; on an empty root it removes the marker. Enter at the start of existing text inserts a blank sibling above. Outdenting a child moves it after its parent's remaining children, keeping their original parent. The first sibling cannot be indented until it has a preceding sibling to become its parent.
The caret stops after the bullet marker when moving left, pressing Home, or clicking in the indentation. Text selections can still include indentation and bullet markers for copying whole branches. Checkbox text remains editable, and code within fences is unaffected. Backspace removes an empty bullet line in one undo step; an empty parent's children are promoted to its level. Items with quote/code content or a reference identity are not treated as empty.
When a bullet's first child is visible, Enter inserts before that child, using its indentation. Splitting text moves the remainder into the new child. Folded branches insert a sibling after their descendants. Set outline.enterCreatesChild to false for sibling insertion throughout. Quotes and fenced code retain their own Enter behavior.
Ctrl+A first selects the item's text, including attached quotes and fenced blocks. Repeated presses include its descendants, then each parent and that parent's descendants, and finally the whole document. A leaf skips directly to its parent on the second press. Moving the cursor or editing resets the sequence. Focused views expand as selection reaches an ancestor; the final step returns to the full source outline. On macOS use Cmd+A.
Multiline paste uses the current item's indentation as its base and preserves nesting within the pasted block. When pasting at the start of an item's text, the first pasted bullet reuses the existing marker instead of doubling it. Pasting inside fenced code stays literal. Use Paste As → Insert Plain Text or disable outline.indentPastedText to paste without this adjustment.
Select several sibling items to indent, outdent, move, duplicate or complete them together. Children always travel with their parent, including folded children. A selection crossing unrelated parent groups is left untouched. Structural shortcuts defer to VS Code while using multiple cursors, snippets or relevant suggestion popups.
The Outline activity-bar view provides a clickable tree and inline completion buttons. Native breadcrumbs, the built-in Outline view and folding gutters understand the hierarchy. Completed and cancelled items are dimmed and struck through. Editor title buttons expand or collapse all branches. The status bar shows item counts and task progress.
Right-click an editor for completion, child insertion, branch selection, duplication and deletion. Each edit is a single undo step. Keyboard shortcuts can be customized in the usual VS Code Keyboard Shortcuts settings.
Settings
| Setting |
Default |
Purpose |
outline.completeSubtree |
false |
Apply completion to descendants too |
outline.taskGroupBy |
"parent" |
Group the Tasks panel by parent, status, or none |
outline.enterCreatesChild |
true |
Enter creates the first child when existing children are visible |
outline.indentPastedText |
true |
Keep multiline paste at the current depth and preserve relative nesting |
outline.dimCompleted |
true |
Dim and strike through completed text |
outline.renderBulletGlyph |
true |
Display all bullets as • dots without changing the file |
outline.fileLinkPickerOnParentheses |
true |
Search workspace files when typing () or [label]() |
outline.imagePreviews |
true |
Inline image thumbnails and larger hover previews |
outline.imageMaxSize |
480 |
Maximum preview width or height in pixels; aspect ratio preserved |
outline.imagePasteFolder |
"" |
Save pasted images in the workspace root, a relative subfolder, or an absolute folder |
outline.showIndentGuides |
true |
Draw guides through parent bullet centers, across wrapped rows |
outline.fadeOpacity |
0.25 |
Opacity of items outside the current fade scope |
outline.liveReload |
true |
Reload JavaScript source in development hosts |
Editor defaults such as wrapping, hidden line numbers and two-space indentation are scoped to [outline] and can be overridden in your settings. The extension draws guides at the actual parent bullet columns; setting [outline].editor.guides.indentation to true switches back to VS Code's standard guides. Example workspace font and spacing preferences are confined to examples/.vscode/settings.json.
Development and verification
npm run check
npm test
npm run test:integration
src/model.js contains pure tree transformations. src/runtime.js connects them to editor commands and language providers. src/extension.js manages development reloads. Unit tests cover tree integrity and edit edge cases; integration tests launch the locally installed VS Code in a separate temporary profile and check actual editing, providers, undo/redo, CRLF and reload behavior. Test profiles and results stay in .dev/.
Drag-and-drop rearrangement, cross-file references, date reminders and syncing are not implemented. Folding is native VS Code folding; completion does not hide items.