Importing PDFs into an Obsidian vault without making a mess

Last reviewed

Obsidian will happily store a PDF and show it in a pane. What it will not do is search inside it well, link into a section of it, show it in the graph, or let you write in the margins as if it were a note.

Converting to Markdown fixes all of that at once, but only if the resulting file is shaped like a note rather than like a transcript. This is the part most imports get wrong.

7 minute read

Decide what the note is before you convert

A 90-page manual converted into one note is technically searchable and practically useless: it is too long to read in a pane, too long to link to precisely, and it will dominate every search result it appears in.

Before converting, decide whether the PDF is one note or several. A paper is one note. A manual is one note per chapter. A book is one note per chapter with an index note linking them. Split the PDF first and convert the pieces — it is far less work than splitting the Markdown afterwards, because you can see the page boundaries in the PDF.

The heading ladder is the note's spine

Obsidian's outline pane, its folding, its heading-level links and much of its search ranking all derive from the heading structure. A note whose headings are wrong is a note whose navigation is wrong.

This is where converted files most often need work, because heading levels come from font sizes and font sizes are only approximately consistent within a document. Two minutes fixing the ladder pays for itself the first time you use the outline pane.

One convention worth adopting: let the note title carry the document name and start the body at H2, rather than opening with an H1 that repeats the filename. Obsidian already shows the filename as the title, so an H1 duplicating it wastes the top of every note.

Front matter that earns its place

Obsidian reads YAML front matter into properties, which drive Dataview queries, the properties pane, and search filters. A converter cannot generate it — none of it is in the PDF — so it is worth adding by hand, once, at import.

Keep it to fields you will actually query. Front matter nobody filters on is just noise at the top of every note.

A front matter block that does useful work
---
title: Distributed Systems Handbook, ch. 4
source: distributed-systems-handbook.pdf
author: R. Mehta
year: 2023
pages: 61-84
tags: [reference, distributed-systems]
imported: 2026-08-04
---

Keep the original PDF, and link to it

Conversion is lossy — figures do not survive, and neither does anything set as an image. Keep the source PDF in the vault, in an attachments folder, and link to it from the note.

That gives you the useful arrangement: the Markdown is what you search, link, quote and annotate; the PDF is what you open when you need the figure on page 12 or need to check a number against the original.

At the top of the converted note
> Converted from [[attachments/distributed-systems-handbook.pdf]].
> Figures and diagrams are in the original.

Do the linking pass while the document is fresh

A converted note arrives with no links, which means it arrives invisible to the graph and unreachable from anywhere else in the vault. Its value goes up enormously with about five minutes of work.

Read the note once and wrap the terms that already exist as notes in double brackets. Where a concept deserves a note that does not exist yet, link it anyway — an unresolved link is a to-do that shows up in the graph, which is exactly where you want it.

Then add the note to whatever index or map-of-content covers its subject. A note that nothing links to will not be found again, however good its contents.

Converting a backlog

If you are importing a folder of PDFs rather than one document, do it in passes across the whole set rather than finishing each note completely before starting the next. Convert everything first, then fix all the heading ladders, then add all the front matter, then do the linking.

It is faster, and it produces a consistent vault — the notes you did last look like the notes you did first, which is not true when you improve your conventions one note at a time.

What not to bother with

  • Do not try to preserve the PDF's page numbers in the note. The Markdown does not paginate, so they refer to nothing.
  • Do not convert scanned PDFs without recognising the text first — you will get an empty note and wonder why.
  • Do not convert a PDF you have the original document for. Convert the original: it has real structure, and no inference is needed.
  • Do not spend time reconstructing complex tables in Markdown. Screenshot the table, keep the PDF link, and move on.