README file from
GithubVault Map
Vault Map writes a single JSON Lines file that indexes every note in your vault: its frontmatter, outgoing links, embeds, citation links, backlinks and broken links, plus vault-wide lists of unresolved links, duplicate titles and orphan notes.
It is meant for tools that work on your vault from the outside, such as scripts or AI coding agents (Claude Code, Codex, Cursor…). Instead of opening hundreds of notes to find out what links to what, they read one small file. Everything comes from Obsidian's own metadata cache, so links are resolved exactly as Obsidian resolves them.
Features
- One click: a ribbon icon and a command (Vault Map: Regenerate map) rebuild the file.
- Automatic updates (optional): regenerate when the vault opens and/or a few seconds after notes change, including changes made by other programs while Obsidian is open.
- Change summary: after each run, a notification tells you how many notes were added, removed or modified, and warns you when a note suddenly loses all its links or when a new duplicate title appears.
- Previous version kept: the old file is saved as
.bakbefore being replaced. The command Vault Map: Show changes since the previous map lists what changed between the two. - Status bar: shows how many notes are mapped and when the map was last generated.
- Exclusions: leave out files and folders with gitignore-like patterns.
Output format
The first line is a metadata object, followed by one line per note, sorted by path.
{"_meta":true,"schema_version":3,"generated_at":"2026-09-25T17:49:33.000Z","generated_by":"vault-map 1.0.0","total_notes":557,"schema_doc":{…},"unresolved_links":{"Missing note":["Folder/Note.md"]},"duplicate_titles":{},"orphans":["Concepts/Leaf.md"],"orphan_folders":["Concepts"]}
{"path":"Concepts/Peat.md","title":"Peat","folder":"Concepts","frontmatter":{"tags":["soil"],"type":"Concept"},"links_out":["Peatland","Missing note"],"embeds_out":["peat-core.jpeg"],"citations_out":[],"line_count":42,"unresolved_out":["Missing note"],"backlinks":["Peatland","Sphagnum"]}
Metadata line
| Field | Content |
|---|---|
_meta |
Always true, to tell this line apart from note lines |
schema_version |
Version of this format |
generated_at |
Date and time of generation (ISO 8601, UTC) |
generated_by |
Plugin name and version |
total_notes |
Number of notes in the file |
schema_doc |
A short description of every note field, so that a reader needs no other documentation |
unresolved_links |
Each broken link target, with the notes that contain it |
duplicate_titles |
Titles shared by several notes (which makes wikilinks ambiguous), with their paths |
orphans |
Notes that no other note links to, limited to the folders chosen in the settings |
orphan_folders |
The folders checked for orphans (empty = the whole vault) |
Note lines
| Field | Content |
|---|---|
path |
Path from the vault root |
title |
File name without .md |
folder |
Parent folder, "" for the vault root |
frontmatter |
Properties as parsed by Obsidian ({} if none) |
links_out |
Targets of the note's links (wikilinks, Markdown links and links in properties): the linked note's title, the file name for attachments, or the raw link text when the link is broken |
embeds_out |
Same, for embeds (![[…]] and ) |
citations_out |
Works the note cites with citation links to a passage, [text](obsidian://cite?note=…&q=…) (the format of the Better Citations plugin; Obsidian itself does not index these links): the cited note's title, doi: and the DOI for a work cited by DOI only, or the raw note name when no note is found. Links in code are ignored |
line_count |
Number of lines, a cheap indication of the note's size |
unresolved_out |
The broken links among links_out |
backlinks |
Titles of the other notes that link to this one |
Links inside code blocks are ignored, as in Obsidian.
Settings
| Setting | Default | Description |
|---|---|---|
| Output file | VAULT-MAP.jsonl |
Path from the vault root. Hidden folders such as .claude/ are allowed, which keeps the file out of your file explorer. |
| Keep the previous version | On | Saves the old file as .bak when it changes. |
| Excluded files and folders | none | One pattern per line. Without /, a pattern matches a file or folder name anywhere (drafts, *.excalidraw.md). With /, it is a path from the vault root (Templates/, Daily/**/2023-*). * matches anything except /, ** matches anything, ? matches one character, and # starts a comment. |
| Folders checked for orphans | none (whole vault) | Only notes in these folders (subfolders included) are reported as orphans. |
| Detail level | Summary | Silent, Summary or Detailed notifications. With Summary, automatic runs stay silent unless something looks wrong. |
| When the vault opens | Off | Regenerate the map at startup. |
| After changes | Off | Regenerate after notes are created, edited, renamed or deleted. |
| Delay | 10 s | How long to wait after the last change before regenerating. |
Privacy
Vault Map works entirely offline. It reads your notes through Obsidian and writes one file (plus its .bak copy) at the path you choose inside your vault. It makes no network requests and collects no data.
Installation
From Obsidian: Settings → Community plugins → Browse, search for Vault Map, then install and enable it.
Manually: download main.js, manifest.json and styles.css from the latest release into <your vault>/.obsidian/plugins/vault-map/, then enable Vault Map under Settings → Community plugins.
Vault Map currently works on desktop only.