What it is (in one line)
A script that scans all Markdown notes in your Obsidian vault and auto-adds links to the matching PDF wrapper notes—so your PDFs show up cleanly in search, backlinks, and graph.
The Story
Recently, as so often, I was thinking about how I could improve my Obsidian setup and took another look at my graph view. Over time, a lot of clutter had accumulated from attachments — especially linked images.
I tried disabling attachments in the graph view, but quickly realized this also removed my linked PDFs, which I still wanted to see. That led me to explore ways to have PDFs represented in the graph view. One option was to create a wrapper note for each PDF. These wrappers link back to the original file, and with the Binary File Manager plugin I could even automate their creation.
Everything seemed perfect until I used it in practice. While writing university notes, I often needed to link to a PDF. With wrapper notes, my links pointed to the wrapper instead of the PDF itself, meaning one extra click every single time. In a daily workflow with dozens of PDF references, this became a major annoyance for the sake of a prettier graph.
So I went back to linking PDFs directly but started manually adding a second link to the corresponding wrapper note, just to keep the graph view clean. As you might guess, that quickly became tedious and felt inelegant.
Then it hit me: “Hey, I can automate this!”
That’s how Obsidian Link Curator was born — a small Python script that automatically adds wrapper-note links whenever a PDF is referenced in a Markdown file. Best of all, with the Shell Commands plugin I can trigger the script directly from inside Obsidian. Since building this tool, working with PDFs has become much smoother: I get direct access when I need it, and my graph view stays meaningful without the clutter.
Why I built it
- I store lots of PDFs in my vault.
- With Binary File Manager, each PDF gets a wrapper note (e.g.,
_Wrapper Notes/Filename_PDF.md) where I can tag and annotate it. - I still found plain
[[file.pdf]]references scattered across my notes.
→ I wanted those notes to also link the wrapper automatically, so metadata, backlinks, and the graph stay useful.
What it detects
The curator scans Markdown for Obsidian-style PDF links, including:
- With or without page numbers:
[[paper.pdf#page=12]] - With or without aliases:
[[paper.pdf|Great paper]] - Plain file links:
[[paper.pdf]]
For each match, it adds (only once) a link to the corresponding wrapper note, like:
<!-- added automatically by Link Curator -->
See also: [[_Wrapper Notes/paper_PDF]]
No duplicates. No noise.
How it fits with my Obsidian setup
- Binary File Manager creates/maintains the wrapper notes for PDFs and other binaries, so I can:
- tag them (e.g., #wrapper)
- write annotations/summaries
- keep the graph clean via tag filters
- Link Curator ensures any note that references a PDF also references its wrapper.
- I trigger it from Obsidian via Shell Commands (or Templater), so it’s one keystroke after I add new sources.
Example flow
- I drop a new PDF into my vault and let Binary File Manager create _Wrapper Notes/My_Article_PDF.md.
- Somewhere I reference it:
[[My_Article.pdf#page=5|Results]]. - I run Link Curator.
- The script updates that note to also include:
[[_Wrapper Notes/My_Article_PDF.md]] - Now the wrapper gets backlinks from all related notes, and I keep using the wrapper for tags, ratings, and highlights.
Nice touches
- Idempotent: it won’t add a second link if the wrapper is already referenced.
- Vault-wide: scans every Markdown file so you don’t have to.
- Page-bundle friendly: works regardless of your folder structure, as long as your wrapper naming is consistent.
Usage (brief)
I run it from Obsidian via the Shell Commands Plugin with a simple command:
python3 /full/path/to/Obsidian_Link_curator.py \
--vault "/path/to/vault" \
--wrapper "_Wrapper Notes"
Full installation & options live in the README.