Constellation: Markdown Graph
See your Markdown notes as a living map. Constellation turns your workspace into an interactive
graph — every note is a node, every link is an edge, and well-connected notes grow larger so the
shape of your knowledge is obvious at a glance. Built for real vaults: it stays smooth from a handful
of notes to tens of thousands.
Great for Obsidian-style vaults, Zettelkasten and "second brain" note systems, documentation
repos, or any folder full of interconnected Markdown.
Features
- Your links, understood — wikilinks (
[[note]], [[note|alias]], [[note#heading]]), embeds
(![[note]]), standard Markdown links, inline #tags, and frontmatter tags/aliases. Links
inside code blocks and comments are ignored, so the graph reflects what you actually wrote.
- Global and local views — explore your whole workspace, or open the local graph to see just the
neighbourhood around the note you're editing. The local graph follows along as you move between
files.
- Powerful filtering — narrow the graph by search text, tags, attachments, orphaned notes, or
link depth. The query language supports
path:, file:, tag:, "exact phrases", -exclusions
and OR.
- Colour groups — highlight parts of your vault with colour rules written in the same query
language (for example, colour everything tagged
#project or under path:daily/).
- Time-lapse — animate your notes appearing in creation order to watch your vault grow.
- Rich interaction — hover to spotlight a note and its neighbours, click to open it (⌘/Ctrl-click
opens to the side), right-click for open / reveal in explorer / copy path / focus local graph /
create note, and drag nodes to rearrange. Pan and zoom with the mouse, arrow keys,
+/-, and
press f to fit everything on screen.
- Tunable layout — adjust the center, repel, and link forces, arrows, label density, node size,
and link thickness to get the look you want. Node positions can be remembered per workspace.
Getting started
- Open a folder or workspace that contains Markdown files.
- Run Constellation: Show Graph View from the Command Palette (⇧⌘P / Ctrl+Shift+P), or press
⌘⇧G ⌘⇧G (Ctrl+Shift+G Ctrl+Shift+G).
- To focus on the note you're editing, run Constellation: Show Local Graph — also available from
the editor title bar and the explorer right-click menu on any Markdown file.
Commands
| Command |
What it does |
Constellation: Show Graph View |
Open the graph for the whole workspace |
Constellation: Show Local Graph |
Open the graph around the active note |
Constellation: Rebuild Index |
Re-scan the workspace and rebuild the graph |
Settings
All settings live under constellation.*:
| Setting |
Default |
Description |
constellation.include |
**/*.md, **/*.markdown, **/*.mdx |
Glob patterns for files treated as notes. |
constellation.exclude |
node_modules, .git, dist, out, build |
Glob patterns excluded from indexing. |
constellation.maxFileSizeKb |
2048 |
Skip files larger than this. |
constellation.maxNodes |
20000 |
Safety cap on rendered nodes; the highest-degree nodes are kept. |
constellation.labelCap |
250 |
Maximum labels drawn per frame. |
constellation.followActiveFile |
true |
Highlight the active note and re-seed the local graph as you switch files. |
constellation.persistPositions |
true |
Remember node positions per workspace and reuse them as the starting layout. |
Your existing files.exclude and search.exclude settings are respected in addition to
constellation.exclude.
Built for large vaults
Constellation is engineered to stay responsive as your notes grow. Parsing runs off the UI thread in
a worker pool with an incremental cache (saving a file re-parses only that file). Layout runs in a
Web Worker using a Barnes–Hut simulation, and rendering uses WebGL so tens of thousands of nodes stay
fluid. When the graph settles, it stops drawing entirely to save battery.
Measured on an M-series laptop: a 10,000-note vault (31k nodes / 65k edges) parses in ~17 ms and each
layout tick runs in a few milliseconds on a background thread, keeping the interface smooth.
Privacy & security
Constellation runs entirely on your machine. The graph view makes no network requests and has no
access to anything outside your workspace. It runs under a strict content-security policy with a
locked-down resource scope.
Feedback
Found a bug or have an idea? Please open an issue at
github.com/alex-sl-eng/constellationGraph.
Contributing
This project uses pnpm (run corepack enable to pick up the right version).
pnpm install
pnpm build # or: pnpm watch
pnpm test # unit + host integration tests
pnpm check # lint + format check + typecheck + tests
Press F5 in VS Code to launch an Extension Development Host, or run pnpm vsix to build a local
.vsix you can install. See the repository for architecture notes and the full test suite.
License
MIT
