← Blog

Bookmarks and outlines when combining PDFs

Outlines reference pages — combining renumbers pages, so links break unless rewritten Input A outline ▸ Cover → page 1 ▸ Introduction → page 2 ▾ Chapter 1 → page 5 ▸ Section 1.1 → page 7 ▸ Section 1.2 → page 12 ▸ Chapter 2 → page 18 page references = object IDs in input A's namespace After combine with B ▸ A: Cover → page 1 ▸ A: Introduction → page 2 ▾ A: Chapter 1 → page 5 ▸ Section 1.1 → page 7 ▸ Section 1.2 → page 12 ▸ A: Chapter 2 → page 18 ▸ B: Appendix → page 25 trees concatenated, no offset rewrite needed for B because pages were already shifted

Outlines (the panel a PDF reader shows as "Bookmarks") are a separate top-level structure inside a PDF. They are not derived from anything visual — they are an explicit, hand-built (or tool-built) tree of named entries pointing into the document. Whether they survive a combine depends entirely on how the combiner treats the catalog's /Outlines entry.

How an outline is stored

The catalog has an /Outlines entry pointing to an outline dictionary, which contains a doubly-linked tree:

/Outlines <<
  /First 12 0 R       % first top-level node
  /Last  18 0 R       % last top-level node
  /Count 5            % total visible (positive) or collapsed (negative) descendants
>>

Each node is a dictionary with /Title, /Parent, /Prev, /Next, /First, /Last, and a /Dest or /A entry pointing to the destination — usually a specific page and view (zoom and scroll position).

The destination almost always uses an indirect reference to the target Page object: /Dest [42 0 R /XYZ 0 612 0]. After a combine, that 42 0 R may have been renumbered to 147 0 R; without rewriting, the bookmark goes nowhere.

Three possible strategies

A merge tool generally has three options for outlines:

Strategy 1: drop everything. Simplest implementation. The combined PDF has no outline. Many free tools do this. Acceptable for short documents users will scroll through anyway.

Strategy 2: keep input A's outline only. A's page references survive intact (its objects keep their original IDs); B's outline is dropped. Useful when A is the "main" document and B is an appendix.

Strategy 3: concatenate. Walk A's outline, copy it into the new file's /Outlines. Walk B's outline, rewrite each destination to point at the renumbered page object, attach as siblings of A's top-level nodes (or wrap in a "Document B" parent for clarity). This is the most useful but also the most work for the merger.

How outlines from multiple input PDFs combine in the output is determined by the underlying merge tool. Typical behavior is to concatenate the outline trees so that Document A's entries appear first followed by Document B's, with destinations rewritten to point at the renumbered pages — but you can confirm by opening the merged PDF in a viewer.

Image pages have no outlines

When you combine images into a PDF, the image-derived pages get no outline entries. They appear in the /Pages array but the outline is silent on them. If you have a 50-page combine of mixed PDFs and JPGs, expect outline jumps that skip over the image pages.

You can manually add outline entries for image pages with a separate post-processing tool. Auto-generating names from image filenames into the outline tree would usually produce ugly results ("scan_2024_03_15_3845.jpg" doesn't make a useful bookmark), so most combiners don't do it.

The /Count field and collapsed state

Each outline node has a /Count integer. Positive means "this many visible descendants when expanded" (the entry is open). Negative means "this many descendants when expanded" (the entry is collapsed). A combine that copies tree fragments needs to recompute counts at every level when subtrees are inserted — failing to do this leaves the outline visually broken (entries that should expand stay closed, or counters are wrong).

/PageMode and the default view

The catalog's /PageMode entry tells viewers how to open the file: /UseNone (no panel), /UseOutlines (open the bookmark panel), /UseThumbs, /FullScreen. Whether and how this entry survives a merge depends on the underlying tool — typically the value from one of the inputs is carried through, often the first one. If you need a specific default view, set it after the merge with a separate PDF-editing tool.

Testing the result

Open the combined PDF in any reader (Preview, Acrobat, evince), open the bookmark panel, click each entry, and verify it lands on the correct page. The most common failure modes are:

Your files are automatically deleted after one hour.