A long PDF without bookmarks is a scroll bar and a hope. Bookmarks are the sidebar entries that let a reader jump straight to a chapter, and almost nothing that produces PDFs adds them automatically — scanners never do, print-to-PDF drivers never do, and merging separate files usually destroys the ones that were there.
Here is what they actually are, and three ways to add them.
Bookmarks are the document outline
In the PDF specification the feature is called the document outline. The catalog dictionary holds an /Outlines entry pointing at an outline tree; each item has a title, a destination, and links to its parent, siblings and children. Viewers render that tree in a sidebar and call it Bookmarks, Contents, Navigation or Index depending on the viewer.
A destination is normally a page reference plus a view specification — for example /XYZ left top zoom, which says "go to this page, put this point at the top-left corner, at this zoom". That is why a well-made bookmark lands on the heading rather than somewhere near it.
Two things follow from this structure.
Bookmarks are not a table of contents page. A contents page is content — visible ink on a page, which may or may not contain links. The outline is metadata, invisible in the page body, and always present in the sidebar. Long documents usually want both, and they are produced by completely different means.
Bookmarks are not the same as links. A link annotation is a clickable rectangle on a page. An outline entry is a sidebar item. A document can have either, both or neither.
Why merged PDFs lose them
Merging is where outlines most often disappear. Combining documents means renumbering every object in the file, and destinations point at page objects. A merge tool that does not rewrite the outline tree along with everything else will either drop it or leave entries pointing at the wrong pages — which is worse, because it looks like it worked.
If you merge first and bookmark afterwards, this stops being a problem. That is the workflow the browser tool below is built for.
Method 1: add them in the browser
Our Add Bookmarks to PDF tool takes one bookmark per line in page: title form:
1: Cover
3: Introduction
9: Chapter 1 - Installation
24: Chapter 2 - Configuration
51: Appendix A - Error codesIt writes a standard PDF outline that appears in Acrobat, Preview, Chrome, Firefox and mobile readers. Everything runs in your browser, so a confidential manual is not uploaded to gain a sidebar.
This is the fastest route for a document you have in front of you, and pasting a whole contents list at once beats clicking through a bookmark panel forty times.
Method 2: qpdf, for inspection and scripting
qpdf can dump the existing outline as JSON, which is the quickest way to see what a file already has:
qpdf --json=latest --json-key=outlines manual.pdfThat prints the outline tree with each entry's title and destination. It is worth running before you add anything — a file that looks bookmark-less in one viewer sometimes has an outline that viewer is not showing.
Method 3: pdftk, for generating from a script
When the bookmarks come from a build process rather than a person, pdftk-java round-trips them as text:
pdftk manual.pdf dump_data output manual.infoThe relevant records look like this:
BookmarkBegin
BookmarkTitle: Chapter 1 - Installation
BookmarkLevel: 1
BookmarkPageNumber: 9
BookmarkBegin
BookmarkTitle: Prerequisites
BookmarkLevel: 2
BookmarkPageNumber: 10Edit that file and write it back:
pdftk manual.pdf update_info manual.info output manual-bookmarked.pdfBookmarkLevel is what gives you nesting: level 1 entries are top level, level 2 entries are children of the most recent level 1, and so on. Dumping an existing file first is by far the easiest way to get the format right.
How to structure an outline people will use
Match the document's own headings. If the reader can see "3.2 Rate limits" on the page, the bookmark should say "3.2 Rate limits" and not "Rate limiting". A mismatch makes the sidebar feel like a different document.
Two levels is usually enough. Three is the practical maximum before the sidebar needs as much navigating as the document. Chapters and their major sections; stop there.
Front matter counts. A cover, contents and preface each deserve an entry. Readers use the sidebar to get back to the contents page constantly.
Keep titles short. The sidebar is narrow and truncates. Put the identifying words first: "Appendix A — Error codes" reads better truncated than "A complete listing of error codes returned by the API".
Number them if the document is numbered. Sorting is by tree position, not by title, but numbered titles let a reader confirm at a glance that nothing is missing.
Checking your work
Open the file and look at the sidebar in at least two viewers. Acrobat, Preview and Chrome all render outlines slightly differently, and Preview in particular hides the sidebar by default, which fools people into thinking the bookmarks did not save.
Then check a couple of destinations land on the right page. Off-by-one errors are the single most common mistake, and they come from the same place every time: a document whose printed page 1 is the third page of the file. Bookmark tools count file pages, not printed page numbers.
Related tools: Add Bookmarks to PDF, Merge PDF for assembling the document first, Add Page Numbers for the printed side of navigation, and PDF Metadata Editor for the title a viewer shows in its window bar.