AeroMD

A VS Code extension that renders an interactive graph view of your Markdown notes – building on the llmwiki / wikilinks concepts.

The extension is published as bpcarson.aeromd; its commands, settings, tools, skill, and artifacts use the AeroMD name.

Features

• Force-directed graph — files are nodes, links between them are edges
• Wiki-link support — parses [[note]], [[note|alias]], [[note#heading]]
• Standard Markdown links — parses [text](https://github.com/bpcarson/aeromd/blob/HEAD/path/to/file.md)
• Optional Python graphing — can graph workspace .py files from import relationships, or mix them with Markdown nodes
• Editor or Explorer view — choose whether the graph opens in an editor tab or in the Explorer side bar
• Open In Editor from the sidebar — launch the current graph into an editor tab from the sidebar title bar
• Click a node to open that file in the editor
• Hover over a node to highlight its direct neighbours and dim the rest
• Search — type in the search box to filter/highlight matching nodes
• Intent-based search — Graph filters labels/paths; Relevance uses QMD BM25 on desktop or built-in BM25 on the web; Semantic/Hybrid use QMD or an explicitly enabled browser embedding model
• Agent-ready graph — a stable v1 extension API, six read-only language-model tools, and a packaged graph-navigation skill let AeroCode-compatible harnesses search and traverse AeroMD
• VS Code for the Web — the same extension runs on vscode.dev without Node polyfills; desktop-only capabilities degrade visibly
• Large-repository budgets — bounded discovery, indexing, webview projection, and payload sizes keep the graph from monopolizing memory
• Active editor highlighting — keeps the open Markdown file and nearby nodes highlighted in the graph
• Layout presets — choose whether the graph feels balanced, calmer/faster-settling, or more lively
• Manual refresh — use the refresh button to rebuild the graph on demand
• Mermaid export — generate README-friendly Mermaid diagrams from the same Markdown graph, including a verbose mode
• Drag nodes to rearrange the layout
• Zoom & pan — scroll to zoom, drag the background to pan; double-click background to reset
• Auto-refresh — the graph updates automatically when Markdown files are created, changed, or deleted

Screenshots

This screenshot is generated by the Playwright browser test in GitHub Actions. It captures the real extension inside a pinned VS Code for the Web workbench rather than a mockup.

Usage

1. Open a workspace that contains Markdown files.
2. Run the command AeroMD: Open Graph View from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. The graph opens in an editor panel or in the Explorer side bar, depending on aeromd.viewLocation.

The command is also available as an icon button (⊞) in the editor title bar when a Markdown file is active.

To export the current workspace graph as Mermaid for GitHub or other Markdown renderers, run AeroMD: Export Mermaid Graph. The extension opens a new Markdown document with a fenced Mermaid block and also copies that block to your clipboard.

If you want more context in the exported labels, run AeroMD: Export Verbose Mermaid Graph from the Command Palette. It keeps the same graph structure but adds folder/path context to node labels when the file is not in the workspace root.

Settings

aeromd.searchBackend remains readable for migration but is deprecated. basic maps to Graph and qmd maps to Relevance until aeromd.searchMode is explicitly set.

Search providers

AeroMD exposes stable search intents and chooses providers internally:

Run AeroMD: Enable Browser Semantic Search to review and approve the pinned model download. AeroMD does not initiate that download during activation or from an agent tool. Literal text/regex lookup remains VS Code Search's job; AeroMD adds document relevance and graph relationships.

Agent tools and extension API

The extension registers aeromd_search, aeromd_get_neighborhood, aeromd_get_backlinks, aeromd_find_path, aeromd_get_document, and aeromd_index_status. They share the graph index used by the UI. The packaged aeromd skill tells compatible agents when to use graph traversal instead of ordinary workspace search.

Other extensions can call await vscode.extensions.getExtension('bpcarson.aeromd')?.activate() and consume the frozen v1 API. Results are bounded; a missing path means no path was found within the current bounded index.

Web-host behavior

QMD is a CLI and cannot run inside the browser extension host. On vscode.dev, Relevance falls back to AeroMD BM25, Semantic uses the optional local Transformers.js worker, and new-window graph opening degrades to a new editor tab. Workspace access uses vscode.workspace.fs, including virtual and multi-root workspaces.

Mermaid export

GitHub can render Mermaid diagrams in Markdown, so AeroMD can export the current workspace graph as a Mermaid flowchart. This export is static, not interactive, but it works in places like README.md where VS Code webviews cannot run.

The standard export uses rounded nodes, a smoother curve, and darker edge styling for better contrast in rendered Markdown. A separate verbose export is available when you want folder context in concept-heavy graphs.

Docs

The repository includes a Diataxis-style documentation set in docs/home.md: tutorials, how-to guides, reference, and explanation pages linked together so they also form a useful graph.

Link formats understood

External URLs (http://, https://, mailto:, etc.) and anchor-only links (#heading) are ignored.

Releases

When package.json's version is bumped on main, GitHub Actions verifies source, bundles, tests, and package contents before creating the matching release, uploading one .vsix asset, and publishing it to the Visual Studio Marketplace when VSCE_TOKEN is configured.

The reusable Publish VSIX workflow also runs for manually published GitHub releases and can be dispatched for an existing release tag.

Normal commits to main do not create releases.

Download the packaged extension from the repository's Releases page, then use Extensions: Install from VSIX... in VS Code to install it locally.

Development

Install Node.js 20+ first so that node, npm, and npx are available in your terminal.

If you do not want to install Node.js locally, use Docker Compose or open the repo in the included Dev Container instead. Both paths provision Node 20, Python 3.12, and the shared nox automation.

# Build the extension host + webview through the shared automation entry point
python -m nox -s build

# Package a VSIX locally
python -m nox -s package

# Rebuild, package, and reinstall into local VS Code + VS Code Insiders
python -m nox -s reinstall

# Run the full local verification pipeline
python -m nox -s verify

# Lower-level npm commands are still available for a tighter inner loop
npm install
npm run compile
npm run bundle-webview

# Run unit tests
npm test

# Run the same verification pipeline in Docker
docker compose run --rm verify

# Build a VSIX in Docker
docker compose run --rm package

python -m nox -s reinstall installs the freshly packaged extension into both ~/.vscode/extensions and ~/.vscode-insiders/extensions, so reloading the window is enough to pick it up.

Press F5 in VS Code to launch an Extension Development Host with the extension loaded.

If npm is not recognized on Windows, install Node.js from nodejs.org and restart VS Code or your terminal.

For containerized local development, run Dev Containers: Reopen in Container in VS Code.

If Docker Desktop is already running, you can skip local Node.js entirely and use compose.yaml instead.

Export

Example Mermaid export of the markdown graph:

%%{init: {"flowchart": {"curve": "basis"}} }%%
flowchart LR
  n0("home")
  n1("reference · docs/reference")
  n2("settings · docs/reference")
  n0 --> n1
  n1 --> n2
  linkStyle default stroke:#6b7280,stroke-width:2px