vault-graph
Interactive graph of an Obsidian vault as a single self-contained offline HTML file
What is it?
What it is
Vault Graph is a deterministic circular visualization of an entire Obsidian vault: each top-level folder forms a wedge whose angle reflects its share of notes, and notes are placed in concentric rings from the center outward according to their connectivity, so the most linked notes appear near the hub and peripheral notes on the rim.
Why it exists
To give users a stable, learnable map of their knowledge base that does not change with each view, allowing them to recognize patterns and navigate without the unpredictability of force‑directed layouts.
Who should use it
Obsidian vault owners who want an offline, deterministic visual graph of their notes, including plugin users and exporters
Who should avoid it
Users needing real-time collaboration, networked access, or those who do not use Obsidian or cannot run Node to generate the exporter
How it works
A quick walkthrough in plain English
How vault-graph works
Step 1 of 3
You interact with it
Open vault-graph, send a request, or connect it to your stack.
Features
Advantages
- Reproducible graph enables learning and recognizing vault patterns
- Fast build time (~0.1s on 450-note vault)
- Complete privacy: no network calls, nothing leaves machine
- Self-contained offline HTML syncs to any device via vault
- Single source builds both plugin and exporter
- Visualizes actual linking structure, not just folder hierarchy
- Auto color slots follow Obsidian theme between light/dark
- Settings scoped per vault in localStorage
- Cross-platform Node.js build with no shell dependencies
- Archive folders stay visible but don't disrupt color rotation
- Built-in smoke tests and synthetic vault generators for development
- Complete architecture decision records in `.ai-context/`
Disadvantages
- HTML export is a static snapshot requiring rebuild for updates
- Note bodies excluded but titles/paths/links are visible in export
- Shared HTML reveals complete note inventory (privacy consideration)
- Graph shape may not match intuitive folder structure
- Word count sizing requires reading note bodies (real I/O cost)
- Discovery requires Obsidian registry, environment variable, or explicit path
- Recording scripts are Windows-only (ffmpeg wrappers)
- No watch mode or live reload capability
- Browser Refresh only returns to defaults, cannot regenerate
Installation
native
**Obsidian plugin — From Obsidian:** Settings → Community plugins → Browse → "Vault Graph" → Install, then Enable. Open it from the ribbon icon or the command palette (*Vault graph: Open the graph*). **Obsidian plugin — Manually:** download `main.js`, `manifest.json` and `styles.css` from the latest release into `<vault>/.obsidian/plugins/vault-graph/`, then reload plugins and enable it. **Obsidian plugin — From source:** `npm install && npm run build`, then `./scripts/install-plugin.ps1`. **Standalone HTML exporter — Get it:** Download the latest release (every tagged version has a `vault-graph-<version>.zip` attached) and unzip it. Or clone: `git clone https://github.com/luke321/vault-graph.git && cd vault-graph`. **Standalone HTML exporter — Generate the file (requires Node 18 or newer):** `node src/build-graph.mjs --vault "/path/to/your/vault"` (the `--vault` flag can be skipped; resolution order is `--vault PATH`, then `VAULT_GRAPH_VAULT`, then `OBSIDIAN_VAULT`, then `--vault-name NAME`, then Obsidian's own registry, then walking up for `.obsidian`). **Standalone HTML exporter — Open that file:** Open the file written by the build (e.g. `<vault>/03 - Resources/Vault Graph/vault-graph.html`) however you open any local file, e.g. `start "path/to/vault-graph.html"` (Windows cmd), `open "path/to/vault-graph.html"` (macOS), or `xdg-open "path/to/vault-graph.html"` (Linux). The output path can be customized with `--out FILE` (e.g. `node src/build-graph.mjs --out ~/Desktop/my-vault.html`).
FAQ
How do I install the Vault Graph plugin in Obsidian?
Open Obsidian, go to Settings → Community plugins → Browse, search for "Vault Graph", and click Install then Enable. You can also install manually by downloading `main.js`, `manifest.json` and `styles.css` from the latest release and placing them in `<vault>/.obsidian/plugins/vault-graph/` before reloading plugins.
What is the standalone HTML exporter and how do I generate a graph from it?
The exporter creates a single offline HTML file that contains the same graph as the plugin, without needing Obsidian. Download the release zip, open a terminal in the repo, and run `node src/build-graph.mjs --vault "/path/to/your/vault"`. It will produce a file like `vault-graph.html` that you can open directly in any browser.
How are top‑level folders coloured and can I customise the colours?
Folders are assigned colours from twelve palette slots (ten hues and two greys) in order, and you can lock a folder to a specific slot in Settings → Community plugins → Vault Graph → Folder colours. Click a slot to fix the colour; **Auto** returns it to its positional slot. Folders whose names start with `_` are archives – they use the darker grey, get no slot, and start hidden unless you change that.
Why does the graph layout not match my folder structure?
The disc layout is deterministic, not force‑directed. Wedges represent the proportion of notes in each top‑level folder, while notes are placed on concentric rings based on how well‑connected they are (central notes have many links, leaves are on the rim). The visual shape therefore reflects the link graph more than the folder tree.
Is it safe to share the generated HTML file? What information does it contain?
The HTML file contains plain‑text metadata for every note – title, path, folder, tags, `created`/`date` frontmatter, word count, and the link graph – but **does not** include note bodies. Treat the file as private by default; a screenshot is usually safer if you want to show the graph without revealing your note titles.
How does the exporter choose which vault to read when multiple vaults are registered?
It follows a resolution order: explicit `--vault` flag wins, then the `VAULT_GRAPH_VAULT` environment variable, then `OBSIDIAN_VAULT`, then `--vault-name` lookup, then Obsidian’s own vault registry, and finally walks up for a `.obsidian` folder. If none is unambiguous, it lists the registered vaults and stops.
Featured in Videos
YouTube tutorials and walkthroughs for vault-graph
Alternatives
Similar projects ranked by category, topics, and text overlap.
