Vault Passport

Vault Passport

Give your Obsidian notes a passport to the outside world.

Obsidian is a powerful knowledge base — but the moment you share a document with someone outside your vault, it falls apart. [[wiki-links]] are meaningless to any reader who does not have your vault. Embedded PDFs become broken references. Citations look like [[Smith 2023]] instead of proper bibliography entries. Look at the showcase document for an example

Vault Passport solves this. It exports any Obsidian document to a polished, self-contained PDF by resolving every [[wiki-link]] into a real citation, building a proper BibTeX bibliography, and running Pandoc to produce output you can hand to a colleague, submit to a journal, or attach to a report — no vault required.

How it works

Every [[linked note]] that exists in your vault becomes a [@cite-key] Pandoc citation. Vault Passport collects all citations, builds a .bib file on the fly, and passes everything to Pandoc with --citeproc so the final PDF has a proper reference list.

No note metadata required. If a linked note has a cite-key in its YAML front matter that value is used as-is. If not, a cite key is automatically derived from the note's name (My Study → [@my-study]) and the filename is used as the title. You can start with zero front matter and add proper bibliographic metadata later.

Notes that do not exist in the vault at all are replaced with readable plain text — no broken link is ever left in the output.

Requirements

Docker. Vault Passport runs Pandoc inside the pandoc/extra container, which ships with XeLaTeX, citeproc, and the Eisvogel template. You do not need to install Pandoc or a TeX distribution separately — only Docker.

Docker on Windows

Docker Desktop is available for Windows and a works with this plugin. The plugin and its Docker integration have been developed on Linux. Windows and MacOS users — we'd love your feedback. If you encounter any path or permission issues please open an issue.

Roadmap

Today every linked note becomes a citation, including ![[transclusions]]. The plan is to eventually inline-expand transclusions properly so ![[Note]] pulls the linked note's content into the document (with ![[Note#Heading]] and ![[Note#^block-id]] doing the obvious thing for sections and blocks), while plain [[wiki-links]] remain citations. Feedback on this direction is welcome on the GitHub issue tracker.

Installation

Via the community plugins browser (once approved)

1. In Obsidian: Settings → Community plugins → Browse
2. Search for Vault Passport, install, then enable
3. Make sure Docker is running

Via BRAT (before approval)

1. Install BRAT from the community plugins browser
2. BRAT settings → Add Beta Plugin → https://github.com/one-wheeled-driver/obsidian-passport
3. Enable Vault Passport under Settings → Community plugins

Manual installation

1. Download main.js and manifest.json from the latest release
2. Place them in your vault's .obsidian/plugins/vault-passport/
3. Enable the plugin in Obsidian

Quick start

1. Open any Markdown note in Obsidian.
2. Open the command palette (Ctrl/Cmd + P) and run "Export document (Vault Passport)".
3. The PDF appears next to the original file.

Plugin settings

How notes become citations

Any [[linked note]] that resolves to a file in your vault becomes a citation in the output:

A note intended as a citable reference might look like this:

---
cite-key: methods2023
author: "Johnson, Alice"
title: "Research Methods in Practice"
year: 2023
type: book
publisher: "Academic Press"
---

The type field maps to BibTeX entry types (book, article, misc, etc.). All fields except cite-key are optional. Supported BibTeX fields: author, title, year, journal, publisher, url, note.

Obsidian link types

All wiki-link variants are handled so the output is readable without the vault:

Sidecar notes for embedded files

When a document embeds a non-Markdown file (e.g. ![[paper.pdf]]), Vault Passport checks for a sidecar note with the same base name (paper.md). If found, the embed becomes a citation using that note's metadata. Otherwise it becomes [Embedded file: paper.pdf].

Templates

The Template name setting resolves in this order:

1. <vault>/<vault-template-dir>/<name> — shared vault template; commit here so everyone working on the vault uses the same one.
2. .obsidian/plugins/vault-passport/templates/<name> — per-user plugin template.
3. The bare name passed to Pandoc for resolution from its data directory (or the container's built-in templates).

Eisvogel

Eisvogel is included in the pandoc/extra Docker image — no separate installation needed. Simply set the template name to eisvogel in the plugin settings.

Template variables

Pandoc passes --var values to the template. These act as defaults — any matching key in the document's YAML front matter overrides them. Set global defaults in the Extra pandoc variables settings box (one key=value per line):

titlepage=true
titlepage-color=2c3e50
titlepage-text-color=FFFFFF
colorlinks=true
numbersections=true

Or put them directly in the document's front matter for per-document control:

---
title: "Quarterly Review"
author: "Alice Johnson"
date: "2026-01-15"
titlepage: true
titlepage-color: "1a1a2e"
colorlinks: true
geometry: margin=2.5cm
---

Eisvogel-specific variables:

Callout conversion

With Convert callouts to boxes enabled, Obsidian callouts are converted to styled LaTeX boxes in the PDF using the awesomebox package (included in pandoc/extra).

> [!NOTE] Optional title
> Body text here.

> [!WARNING]
> No title — the type name is used automatically.

The +/- fold modifiers are silently stripped. Regular blockquotes without [!TYPE] are left untouched.

Callout type mapping

Strict mode

By default, links to notes that are missing from the vault are replaced with plain text and a warning is printed in the developer console. With Strict mode enabled, the export aborts on the first missing note. Useful when you want a broken link to be a hard error instead of silent plaintext fallback.

Output

Input:  /vault/my-paper.md
Output: /vault/my-paper.pdf                                          ← PDF next to original
        .obsidian/plugins/vault-passport/build/my-paper.md          ← intermediate markdown
        .obsidian/plugins/vault-passport/build/references.bib       ← generated bibliography

Development

npm install
npm test               # 270+ unit/integration tests with Vitest
npm run test:coverage  # coverage report
npm run build          # type-check + esbuild → main.js
npm run lint           # eslint

Pure logic (src/lib/) is 100% Obsidian-free and tested in plain Node. Services and pipeline modules use a small hand-rolled mock of the Obsidian API in tests/helpers/obsidian-mocks.ts.

A real-Docker smoke test that produces an actual PDF is available via npm run test:manual (gated separately because it spawns Docker and takes ~15s).

Contributing

Bug reports and pull requests are welcome at github.com/one-wheeled-driver/obsidian-passport.

License

MIT — see LICENSE.