BASALT · JOURNAL
Editing the bookmarks in a PDF on a Mac
Bookmarks are the only navigation a long PDF has. When a two hundred page bundle arrives with no outline, or with an outline inherited from four source documents, the reader's first ten minutes go to scrolling. Preview will show you an outline and will not let you restructure one.
The outline is a tree of dictionaries
The document catalog has an /Outlines entry pointing to the outline root. Under it, each bookmark is a dictionary with a /Title string, a /Parent reference, /Prev and /Next references to its siblings, and /First and /Last references to its children. It is a doubly linked tree, and the nesting in the sidebar is that tree's shape.
Each bookmark carries a target in one of two forms. A /Dest entry points at a destination directly: an array naming a page object plus a view specification such as /XYZ with coordinates and a zoom, or /Fit. Alternatively /A holds an action dictionary, usually a /GoTo action carrying the same kind of destination, though it can be a /URI or /Launch action instead.
Named destinations, and why they break
Instead of naming a page object, a destination can be a name resolved through the /Dests name tree in the names dictionary. The bookmark says "Exhibit C" and the name tree says where "Exhibit C" is.
The indirection survives page reordering: move the pages, update one name tree entry, and every bookmark and internal link still works. It is also what breaks most often, because a tool that rewrites the page tree without carrying the name tree forward leaves every bookmark pointing at a name that no longer resolves. The outline still displays, and clicking an entry does nothing.
Direct destinations fail differently. They reference a specific page object, so a rewrite that removes or renumbers pages can leave a destination silently pointing at the wrong page. That is worse, because it looks like it worked.
What ordinary document work does to an outline
Merging is the usual culprit. A correct assembler creates a new outline root, re-parents each source outline under it, and rewrites every destination to the pages' new positions. Tools that do less produce three predictable failures: the outline is dropped entirely, only the first document's outline survives, or all of them survive with destinations still referring to original page indices, so every entry after the first document is off by however many pages preceded it.
Splitting has the mirror problem. Pull pages 40 to 90 out of a bundle and the extract should carry the subtree covering those pages with destinations rebased. Many tools ship the extract with no outline at all, and repairing that afterward is one of the PDF jobs that keeps interrupting the real work. Page reordering and deletion invalidate direct destinations unless the tool updates them.
Bookmark text is disclosure
An outline is plain text stored in the file, written by whoever assembled the document, usually quickly and usually in internal shorthand.
A bookmark reading "Exhibit C: patient records, M. Alvarez" is readable regardless of what was done to page fourteen. If page fourteen was redacted, the outline entry naming the patient is still in the /Outlines tree, extractable by anything that reads the catalog and visible in the sidebar of any viewer.
The same applies to entries like "draft, do not send", "per call with counsel", and internal matter numbers. They survive because cleanup routines think about pages and metadata, and the outline is neither. What a PDF still carries after you think you cleaned it puts this alongside the other structures that outlive the content they describe. There is a second-order version too: a bookmark pointing at a deleted page proves the page existed and describes what was on it.
Editing without rebuilding the file
The useful operations are small and specific. Rename an entry so it says something a reader outside your firm will understand. Delete entries that name people or reveal internal process. Re-nest a flat list into sections. Fix the destinations a merge left pointing at the wrong page. Remove the outline entirely when a file is going out and the navigation is not worth the disclosure.
Doing this by hand is possible. qpdf --qdf --object-streams=disable expands the file so the outline dictionaries are readable and /Title strings can be edited in place, but you have to maintain /Prev, /Next, /First, /Last, /Parent, and the /Count on each parent. Getting /Count wrong makes viewers render the tree strangely or not at all, and deleting a node means relinking its siblings.
For a one line title fix that is fine. For restructuring a bundle it is not. Whatever you use, the edit should be written as a fresh generation rather than an incremental update, or the previous outline, including the entry you deleted because it named someone, remains in the earlier revision inside the same file.
What Preview will and will not do
Preview displays a table of contents when one exists and lets you jump through it. It does not let you add, rename, re-nest, or delete outline entries, and it does not repair destinations. Its thumbnail sidebar handles page order, not navigation structure.
This is consistent with how it handles the rest of the container. Preview is a viewer with a few editing conveniences, and the structures beside the page tree are outside its scope, which is also why it is not the right tool for removing text permanently.
Frequently asked questions
How do I edit PDF bookmarks on a Mac?
Editing bookmarks means modifying the outline dictionaries under the catalog's /Outlines entry, which requires a tool that maintains the tree: the /Prev, /Next, /First, /Last, and /Parent links and the /Count on each parent. Preview displays an existing outline but cannot add, rename, re-nest, or delete entries. The change should be written as a fresh generation rather than an incremental update.
Can Preview add bookmarks to a PDF?
No. Preview shows a document's existing table of contents and lets you navigate it, but provides no way to create an entry, rename one, change nesting, or repair a destination pointing at the wrong page. Its sidebar handles page order and page-level operations. Restructuring navigation requires a tool that writes the outline tree in the document catalog.
Why did my bookmarks stop working after merging PDFs?
Because the merge did not rewrite the destinations. Each bookmark points either at a specific page object or at a name resolved through the /Dests name tree, and both references have to be rebased when pages move into a combined document. Assemblers that skip this leave entries pointing at original page indices or at names that no longer resolve, so a click lands on the wrong page or does nothing.
Do PDF bookmarks contain text that can be extracted?
Yes. Every outline entry stores its label as a plain /Title string in the document catalog, entirely separate from page content, so it extracts whether or not the pages it points to still exist or have been redacted. A bookmark naming a person, a matter, or an internal status discloses that text to anyone who opens the file, and page-level redaction does not touch it.
Should I remove bookmarks before sending a PDF out?
Remove them if the labels carry internal shorthand, names, or process detail you would not put on a page, and keep them if they are neutral section headings a reader outside your organization benefits from. The decision is about the text, not the feature. A middle path is renaming entries to neutral descriptions rather than leaving a long document with no navigation.
What is a named destination in a PDF?
A named destination is an entry in the /Dests name tree mapping a name to a page and view specification, so bookmarks and internal links can target the name instead of the page object directly. The advantage is that reordering pages requires updating only the name tree. The failure mode is that a tool rewriting the page tree without carrying the name tree forward leaves every reference unresolvable.
Do bookmarks survive splitting a PDF?
Only if the splitting tool carries the relevant part of the outline into the extract and rebases its destinations to the new page numbering. Many tools produce extracts with no outline at all, which is why a fifty page excerpt from a bundle so often arrives without navigation. If the split is the last step before sending, check the extract rather than assuming it inherited one.
Does editing bookmarks change the pages of a PDF?
No. The outline lives beside the page tree in the document catalog and only references pages, so renaming, re-nesting, or deleting an entry leaves page content untouched. The caveat is how the change is written: an editor that saves it as a fresh generation rebuilds the file, whereas an incremental save appends the new outline while the old one remains in the previous revision.
Doing it in Basalt
Basalt edits or removes bookmarks as part of its clean up tool, alongside removing optional layers and embedded files, and saves the result as a cleaned copy. Every tool in the app writes a new file, so the original stays exactly as it was.
Because merging and splitting live in the same window, you can combine a bundle, fix the outline the merge produced, and inspect what the combined file is carrying without moving the document between applications. Parsing happens in a sealed engine process holding no network entitlement, enforced by macOS at the code signature level, so nothing leaves the Mac. It is $29 once for up to three Macs, with a 24 hour free trial.
Redaction that proves itself
Basalt destroys the content you mark, then re-opens the file it wrote and proves the content is gone before it saves anything. Your documents never leave your Mac.