Where your PDF’s bookmarks go when a tool rebuilds it

Bookmarks disappear from a PDF because they were never on the pages to begin with. The outline you click in a viewer's sidebar is a separate navigation tree stored at the document level, pointing at pages rather than living on them. So the moment a tool rebuilds your document out of its pages — which merging, splitting, deleting and reordering all do — the outline is left behind, because it belonged to the old document and not to any page that got copied across.

This is the same mechanism that makes a filled form come back blank, and it is worth seeing them as one fact rather than two surprises. A PDF has things that belong to individual pages and things that belong to the document as a whole, and most "edit" operations quietly rebuild the second kind out of the first.

Copy-based tools cannot carry the outline

The tools that drop bookmarks all work the same way: they create a new, empty PDF and copy the pages you want into it. Merge, Split, Delete Pages, Extract Pages and Organize Pages are all copy-based. Copying a page brings the page across perfectly — its text, its images, its exact appearance — but the outline is not a property of any page, so there is nothing on the page for the copy to pick up. The result is a flawless set of pages with an empty sidebar. This is not a bug that could be fixed with more care; it is what "rebuild from the pages" means.

The document title and author go the same way, and for the same reason — they are document-level too. If bookmarks matter to a document you are about to merge or reorder, the sequence that works is to do the structural edit first and add the outline last, because the outline you add will survive anything that does not rebuild the document again.

Why editing bookmarks needs two different libraries

Reading an existing outline and writing a new one are split across two libraries in our bookmarks editor, and the split is not an accident. Reading is done with pdf.js, because it resolves each outline entry's destination to a real page index the way a viewer does — an outline points at a location, sometimes indirectly, and working out which physical page that lands on is exactly the job a renderer already does well. Nested outlines are flattened into a single list, since the editor is flat, and it warns you when the original had nesting so that saving a flat version is a choice you made rather than a tree you lost silently.

Writing is done with pdf-lib, which has no outline feature at all, so the tree is built by hand. An /Outlines dictionary is created, then one small dictionary per bookmark, each linked to the next in a sibling chain and each pointing at its page through a "fit the page" destination. Titles are written as hex strings so that a bookmark named in another language survives intact. It is fiddly, low-level work — the kind a higher-level API usually hides — and it exists because there was no API to hide it.

Replacing an outline means the old one has to leave

Saving a new outline replaces the old one, and "replace" has to mean the old tree's data is genuinely gone, not merely unpointed-at. This is a trap the library sets: pdf-lib writes out every object it has registered, so dropping the pointer to the old outline is not enough — the orphaned tree would still ship in the saved bytes, just with nothing linking to it. The editor deletes the old outline object from the document itself, so it actually leaves the file. It is the same lesson that stripping metadata had to learn: removing a reference is not the same as removing the thing, and only one of them is what a person cleaning up a document actually wants.

Editing bookmarks is mutate-in-place, so it touches only the outline — your pages, their text and everything else are left exactly as they were. That is the opposite of the copy-based tools above, and it is why you can re-point a bookmark or rename a section without any risk to the document's appearance. The rule that falls out of all this is short: build your bookmarks after the structural edits are done, and they will stay put.

A bookmark points at a page, and pages move

A bookmark is a title plus a destination — go here — and the "here" is a specific page. This is why reading an outline resolves each destination to a real page index the way a viewer does, instead of trusting a stored page position: reordering or deleting pages can invalidate that stored position, and asking the document where the destination actually lands is the only way to be sure it is right. When you save a new outline here, each entry is pointed straight at the page you chose, so it is correct for the document as it stands now — not as it stood before you rearranged it.

There is a knock-on worth planning for. Because the bookmarks editor is mutate-in-place and the copy-based tools are not, the two do not commute: bookmarks added before a merge vanish, bookmarks added after a merge survive. So the reliable recipe for a document assembled from several sources is to do every structural edit first — merge, reorder, drop the pages you do not want — and only then open the result and build the outline against the pages as they finally sit. In that order the outline is the last thing added and the first thing that stays.

• Bookmarks are a document-level outline that points at pages; they are not stored on the pages.
• Copy-based tools (merge, split, delete, extract, organize) rebuild from pages and cannot carry the outline — or the title and author.
• Mutate-in-place tools, including the bookmarks editor itself, leave the outline alone.
• Add or edit bookmarks LAST, after any merging or reordering, so nothing rebuilds the document out from under them.