Outline for VS Code

Browse and edit documents from an Outline instance directly inside VS Code, using a WYSIWYG Markdown editor that lives in the sidebar — or, on demand, in a full editor tab.

Status: unpublished. Run from source via the Extension Development Host, or package locally as a .vsix.

Features

• Tree view of Collections and nested Documents in a dedicated Activity Bar container.
• WYSIWYG Markdown editor in the sidebar (powered by Milkdown / ProseMirror), with CommonMark + GFM support — including task lists with clickable checkboxes.
• Same editor in an editor tab when you want more screen real estate. Re-opening the same document reveals the existing tab rather than duplicating.
• Debounced autosave to Outline (documents.update) on a 1.5s debounce, on blur, on Ctrl+S/Cmd+S, and on window close. Coalesces rapid edits into a single in-flight request.
• Smart background sync: every 5s the currently visible document is polled. If the server has a newer version and you're idle, it silently reloads. If you have unsaved local edits, a non-modal banner appears with Reload / Dismiss. Polling pauses when the editor isn't visible, the VS Code window loses OS focus, you're not signed in, or a save is in flight.
• Authenticated image proxying: private Outline attachments render inline by being fetched through the extension (with your bearer token when same-origin) and swapped in as data URIs. Tokens are never embedded in document content.
• Raw Markdown access via a outline: FileSystemProvider for power users who'd rather edit the source. Conflict-detected on save.
• Works with Outline cloud and self-hosted instances.

Setup

1. In Outline, go to Settings → API & Apps and create a personal API key (it looks like ol_api_…).
2. In VS Code, click the Outline icon in the Activity Bar, then Sign in to Outline (or run Outline: Sign In from the command palette).
3. Enter your instance URL (e.g. https://app.getoutline.com or your self-hosted URL — no /api).
4. Paste the API key. It is stored in VS Code's SecretStorage.

Usage

Browsing

• Expand a collection in the Documents view to see its document tree (nested children supported).
• Single-click a document → loads in the Editor view directly below in the sidebar.

Editing

• Type — autosave runs ~1.5 s after you stop typing, and on blur, Ctrl+S/Cmd+S, or window close.
• The status line at the bottom of the editor shows Editing… / saving / Saved and any errors.
• Task lists: type [ ] something or [x] done at the start of a line to create a checkbox; click the checkbox to toggle it.

Opening in a larger view

On any document in the tree:

• Inline split-icon (visible on hover) → open the same WYSIWYG editor in an editor tab to the side.
• Right-click → Open in Editor → open in the active editor column.
• Right-click → Open in Editor to the Side → side column.
• Right-click → Edit Raw Markdown → opens the document source via the outline: filesystem provider for direct Markdown editing (with conflict detection on save).

The same document opened twice (e.g. sidebar + editor tab) reuses the same panel rather than duplicating.

Background sync

While a document is open in the editor view (sidebar or tab), is visible, and VS Code has OS focus, the extension polls Outline every 5 s for that one document:

• If you're idle (local content matches what was last saved) and the server has a newer version → silent reload, no prompt.
• If you have unsaved edits → a yellow Reload / Dismiss banner appears at the top of the editor (once per stale event). The banner clears after the next successful save or reload.

Polling never overlaps requests, never polls more than the one focused document, and never polls the tree.

Configuration

Setting	Default	Description
outline.baseUrl	https://app.getoutline.com	Base URL of the Outline instance. Do not include /api.
outline.debug	false	Log API requests and errors to the Outline output channel.

Commands

All commands are under the Outline: category in the command palette.

Command	Description
Outline: Sign In	Prompt for instance URL and API key, validate, store.
Outline: Sign Out	Forget the API key.
Outline: Refresh	Reload the collections / documents tree.

The following commands exist but are wired only to context menus / inline icons (not the palette):

• outline.openDocument — open in sidebar editor (the default tree-click action)
• outline.openInEditor — open the WYSIWYG editor in a tab
• outline.openInEditorToSide — open in a side column
• outline.editRawMarkdown — open as raw Markdown via the outline: FS provider

Running from source

git clone <this repo>
cd vscode-outline
npm install
npm run compile          # or `npm run watch` for incremental rebuilds

Then open the folder in VS Code and press F5 to launch the Extension Development Host. Use Ctrl+R in the dev host to reload after editing source.

Scripts

Script	What it does
npm run compile	Build extension + webview bundles into dist/.
npm run watch	Webpack in watch mode.
npm run package	Production build (minified, hidden source maps).
npm run lint	ESLint over src/**/*.ts.
npm run test-compile	TypeScript type-check only (tsc -p ./).

Packaging as a .vsix

npm i -g @vscode/vsce
vsce package

Produces vscode-outline-<version>.vsix. Install via VS Code → Extensions view → … menu → "Install from VSIX…", or:

code --install-extension vscode-outline-<version>.vsix

Architecture

See ARCHITECTURE.md for an overview of the major modules and how they interact.

Limitations

• Read + edit only — no creating, renaming, deleting, or moving documents/collections from VS Code.
• Outline-flavored Markdown extensions (notice/info blocks, embeds, math, etc.) are not in the CommonMark/GFM presets used by Milkdown and may render as plain paragraphs or be mangled on round-trip. Use Edit Raw Markdown if you need to author them.
• Image upload is not supported — drag-dropping an image into the editor will not persist it to Outline.
• The collections/documents tree is cached for the session — use Outline: Refresh after major changes upstream.
• No real-time collaboration; concurrent edits are handled by the polling banner and a "last write wins" save (the raw-Markdown path additionally has a save-time conflict prompt).

License

MIT.