PDF bookmarks explained: how the outline panel works

PDF bookmarks are the clickable, nested list in a viewer's sidebar that jumps to chapters and sections. The PDF standard calls this the document outline. It is separate from the pages, which is why bookmarks can be missing from a file that looks perfect, and why they often disappear after editing. The outline viewer shows a PDF's bookmarks as a list with page numbers; this guide explains what sits behind them.

What bookmarks are

Each bookmark has a title and a target. The target is usually a destination: a page plus a view, such as a position and zoom level, or "fit the whole page". It can instead be an action, most often opening a web link. Bookmarks can be nested to any depth, so a book might have parts, chapters and sections, and each level can be shown expanded or collapsed when the file opens. Some editors also let you colour a bookmark or set it in bold or italic.

How the outline is stored

The outline is a tree of objects hanging off the document's catalog, the root object of the file. Each item points to its parent, its first and last children, and its previous and next siblings; a count records how many descendants are open, with a negative count meaning the item starts collapsed. Destinations can be written directly or by name, where the bookmark says "go to chapter-3" and a separate table maps that name to a page. Because the tree belongs to the document rather than to any page, How PDF files work: why some have text and some are pictures is a useful companion here.

Bookmarks, contents pages and tags

Three different things are easy to confuse. Bookmarks live in the sidebar. A table of contents page is printed on a page, sometimes with link annotations over each line so it is clickable. Tags describe the logical structure (headings, paragraphs, lists) for screen readers and reflow. A well-made document has all three, generated from the same headings. For accessibility, the W3C's guidance for WCAG lists bookmarks as a way to help people navigate long PDFs, so it is good practice to include them in anything more than a few pages long.

How bookmarks get created

The reliable way is to use real heading styles in the source document and let the export create the outline. Word's save-as-PDF options include creating bookmarks from headings; LibreOffice has an export outlines option; LaTeX does it with the hyperref package. Bookmarks added by hand in a PDF editor work too, but they drift out of date when pages change. If your headings are typed as bold body text rather than heading styles, the exporter has nothing to build an outline from.

Why bookmarks go missing

Scanned documents have no outline unless someone adds one, and many quick exports skip it. The other common cause is editing. Tools that build a new PDF by copying pages, including my own merger and splitter, copy what is on the pages but not the document-level outline, so the result starts without bookmarks. When a bookmark survives but its target page was removed, it points nowhere. If bookmarks matter, add them at the end, after merging and splitting, or regenerate the PDF from its source. How to merge PDF files into one, and what to check first lists what else a merge leaves behind.

Checking a document

Drop a PDF into the outline viewer and it lists every bookmark, indented by level, with the page number each one jumps to, plus a count of bookmarks and levels. Bookmarks that open a web link are marked as links, and the occasional named destination that cannot be resolved shows a dash. You can copy the outline as indented text with dot leaders or as a Markdown list, which is handy for reading plans, reviews and documentation, or for working out page ranges before splitting. It also tells you plainly when a file has no outline. The PDF is read on your device with the open-source pdf.js renderer; encrypted files may not open. For a flat dump of the words rather than the structure, use text extraction.