Vault Linker
Overview
Vault Linker links note titles and YAML aliases across your Obsidian vault as wikilinks. Use the CLI (vaultlinker) for batch jobs, parallelism, and automation, or the community plugin for link, audit, and unlink from inside Obsidian.
Linking
Obsidian graph view before and after running Vault Linker on a vault (illustrative).
Features
- Automatic wikilinks for note titles and YAML aliases
- Parallel runs with
--jobs(read / process / write phases) - Dry-run, backup, output copy, globs, and incremental state
- Audit broken links, pending links, and backlink stats; unlink managed title links
- Skips metadata, code blocks, embeds, and markdown links (CLI + plugin)
- Optional case-sensitive matching and first link per phrase per note
- Path include/exclude globs (CLI flags; plugin settings)
Linking Process
- Scan Files: The tool scans all the markdown files in your Obsidian vault.
- Extract Filenames: It extracts the filenames from the scanned files.
- Match Filenames: It matches the filenames with the content in other files, ignoring the case.
- Insert Links: When a match is found, it inserts a Wikilink in the content, preserving the original case of the filename in the link.
- Skip Metadata and Code: The tool skips adding links in metadata sections and code blocks to avoid unwanted linking.
Examples
- Simple Linking: If a file named
Object-Oriented Programming.mdexists and another file mentions "object-oriented programming", the tool will link it as[[object-oriented programming]]. - Preserve Case: If the mention is "Object-Oriented Programming", the link will be
[[Object-Oriented Programming]]. - No Links in Code Blocks: Mentions inside code blocks are ignored.
- No Links in Metadata: Mentions inside metadata sections are ignored.
- Multiple Links: If multiple files are mentioned, each will be linked appropriately.
- Partial Matches: If a file named
Object.mdexists, mentions of "object" will be linked as[[object]], but "objects" will not be linked. - Complex Linking: If files named
Object-Oriented Programming.md,Functional Programming.md, andObject.mdexist, and another file mentions "object-oriented programming", "functional programming", and "object", each will be linked as[[object-oriented programming]],[[functional programming]], and[[object]]respectively. Note "object" will not be added inside "object-oriented programming".
Installation
From PyPI
Package: vaultlinker on PyPI
pip install vaultlinker
vaultlinker /path/to/vault/ --help
From source
Clone the repository and install the package (recommended):
git clone https://github.com/arshad115/vault-linker.git
cd vault-linker
pip install -e ".[dev]"
For a quick script-only install without the console command:
pip install -r requirements.txt
Usage
vaultlinker dry run with verbose progress (-v) and eight workers (--jobs 8).
After installation:
vaultlinker /path/to/vault/
Or run the module directly:
python vaultlinker.py /path/to/vault/
Use -v / --verbose for progress bars and scan details (default is quiet except warnings and the summary).
Parallel processing (read, link, and write phases):
vaultlinker /path/to/vault/ --jobs 8
vaultlinker /path/to/vault/ --jobs 0 # automatic worker count
Safety options
Preview changes without writing files:
python vaultlinker.py /path/to/vault/ --dry-run
Write linked copies to another directory (vault files stay unchanged):
python vaultlinker.py /path/to/vault/ --output /path/to/linked-vault/
Create a .bak copy of each file before overwriting it in the vault:
python vaultlinker.py /path/to/vault/ --backup
Skip linking a note's title inside its own file (e.g. do not turn README into [[README]] in README.md):
python vaultlinker.py /path/to/vault/ --no-self-links
By default, markdown under .obsidian, .git, attachments, and similar folders is skipped. Add more directory names with --exclude DIRNAME, or pass --no-default-excludes to scan everything.
Limit which notes are processed with vault-relative globs:
vaultlinker /path/to/vault/ --include-glob 'notes/**' --exclude-glob 'templates/**'
Obsidian-aware linking
- Aliases: YAML
alias/aliasesin front matter are link phrases; matches use[[Note Title|alias]]when the visible text differs from the note title. - Embeds & markdown links: Text inside
![[...]]and[label](url)is not linked. - Headings: Text on
# headinglines is skipped unless you pass--link-headings. - Duplicate filenames: If two notes share the same filename in different folders, the tool warns and uses the note with the longest path as the link target for that title.
--use-headings: Also link phrases taken from each note's first# H1heading.--no-aliases: Only use filenames, not front matter aliases.
Audit and unlink
Audit the vault (no file changes):
vaultlinker /path/to/vault/ --audit
vaultlinker /path/to/vault/ --audit -v # include pending link details
Reports pending links (same rules as a dry run), broken [[wikilinks]] with no matching note, notes with zero incoming links, and the most-linked titles.
Remove wikilinks that this tool would create (title and alias forms only; manual links to other targets are kept):
vaultlinker /path/to/vault/ --unlink --dry-run
vaultlinker /path/to/vault/ --unlink --backup
Incremental and blocklist
Re-run only notes that changed since the last successful incremental run (state is stored in .obsidian/vault-linker-state.json). If notes are added or removed, every note is processed again so new titles can link correctly.
vaultlinker /path/to/vault/ --incremental
Skip noisy short titles or specific words:
vaultlinker /path/to/vault/ --ignore-phrase README --min-title-length 4
vaultlinker /path/to/vault/ --ignore-file ./linker-ignore.txt
vaultlinker /path/to/vault/ --case-sensitive --first-link-per-phrase
CI / GitHub Actions
See docs/github-actions.md and the example workflow .github/workflows/vault-linker-example.yml.
Obsidian plugin
Install Vault Linker from Settings → Community plugins, or build from plugin/ (source). Release assets (manifest.json, versions.json, main.js) live at the repo root for Obsidian’s directory scanner.
See plugin/README.md and PUBLISHING.md.
Make sure to back up your vault before using this tool, as in-place runs can make irreversible edits unless you use --dry-run or --output.
Running Tests
To run tests for Vault Linker, use the following command:
pytest
This will execute all the tests and provide you with a summary of the results. Make sure you have all the necessary dependencies installed before running the tests.
TODO
- Add support for alias links
- Multithreading
- Write additional tests for edge cases
- Make it into a plugin for Obsidian
Contributors
Contributing
We welcome contributions to Vault Linker! If you have an idea for a new feature or have found a bug, please open an issue or submit a pull request.
Steps to Contribute
- Fork the repository.
- Create a new branch for your feature or bugfix:
git checkout -b feature-name
- Make your changes and commit them:
git commit -m "Description of your changes"
- Push your changes to your fork:
git push origin feature-name
- Open a pull request on the main repository.
License
This project is licensed under the MIT License. See the LICENSE file for more details. © Arshad Mehmood
Metadata
Release files for vaultlinker 0.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vaultlinker-0.5.1.tar.gz | 21.3 kB | With provenance | Details for vaultlinker-0.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vaultlinker-0.5.1-py3-none-any.whl | Python 3 | none | any | Details for vaultlinker-0.5.1-py3-none-any.whl |
Total release size: 43.7 kB
Release files / vaultlinker-0.5.1.tar.gz
| Download URL | vaultlinker-0.5.1.tar.gz |
|---|---|
| Size | 21.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f07a92a8ef67db2f6dcc1fd32af45bff4f9e0c2b8e7913b0e5e4b0cf4368233
|
|
BLAKE2b-256 checksum How to use checksums |
a4b38aefc9073e75152054bcd97ea261d6e446701e111f5faff77baac4c9e330
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / vaultlinker-0.5.1-py3-none-any.whl
| Download URL | vaultlinker-0.5.1-py3-none-any.whl |
|---|---|
| Size | 22.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b52e8bd4e3df10d5221357c416abf9b3caa308407a0736318917423e7d2967ac
|
|
BLAKE2b-256 checksum How to use checksums |
ef6325077842a58b534e029b6cd1948bfbab1ab9b0a50f3722ac0b5cc5600bc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logSecurity for vaultlinker 0.5.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vaultlinker-0.5.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.