How to Parse a PDF's Bookmark Tree in the Browser with pdf-lib
How to Parse a PDF's Bookmark Tree in the Browser with pdf-lib PDF bookmarks are one of those features that users notice only when they are missing. Open a long report, textbook, or technical manual. You expect a navig
How to Parse a PDF's Bookmark Tree in the Browser with pdf-lib
PDF bookmarks are one of those features that users notice only when they are missing.
Open a long report, textbook, or technical manual. You expect a navigation panel with chapters, sections, and subsections.
Sometimes it's there. Sometimes it's completely empty.
As a developer, I wanted to understand how to read that structure directly in the browser.
First, they are called outlines
The PDF specification uses the term outlines for what most PDF readers call bookmarks.
An outline is a navigation tree stored inside the PDF document.
It can contain:
Top-level chapter names.
Nested section names.
Links to specific pages or destinations.
Parent-child relationships between entries.
A simple document might have five bookmarks. A large textbook could have hundreds.
And some PDFs have none at all.
This is not necessarily a broken document. Many PDFs are generated without bookmark information in the first place.
The pdf-lib limitation
I use pdf-lib for several browser-based PDF operations.
It is useful for reading and modifying PDF documents, but there is an important limitation here.
The standard PDFDocument API does not expose a complete, high-level bookmark tree reader.
You should not assume that loading a PDF gives you access to its outlines.
For a real implementation, you need to inspect the PDF catalog and its /Outlines entry, then resolve the linked outline objects.
Here is a simplified sketch of how I approach that with a PDF object parser:
JavaScript
import { PDFDocument } from 'pdf-lib';
async function inspectBookmarks(file) {
try {
const bytes = await file.arrayBuffer();
const pdfDoc = await PDFDocument.load(bytes);
const catalog = pdfDoc.catalog;
const outlines = catalog.get(
PDFDocument.PDFName.of('Outlines')
);
if (!outlines) {
return {
success: true,
bookmarks: [],
message: 'No outline tree found.'
};
}
// Resolve the outline dictionary before traversing it.
const outlineRoot = pdfDoc.context.lookup(outlines);
return {
success: true,
outlineRoot
};
} catch (error) {
return {
success: false,
bookmarks: [],
error: error.message
};
}
}
This is an inspection starting point, not a complete bookmark parser. A production parser still needs to traverse /First, /Next, and /Last, resolve destinations, and handle nested /First entries.
Why bookmark counts vary
The PDF format does not require every document to have an outline tree.
A scanned document may contain hundreds of pages but zero bookmarks.
A digitally generated report may have a well-organised tree.
A document assembled from several PDFs may have inconsistent navigation, depending on how the merge operation handles document structure.
There is another problem: bookmark destinations are not always simple page numbers. They can contain destination arrays, named destinations, and view settings.
So counting outline entries is only the beginning.
Bookmarks are hints, not promises
A bookmark is a navigation aid.
It does not guarantee that its destination is valid, that the page still exists, or that the title accurately describes the content.
A good implementation should handle missing outlines, broken references, and unsupported destination types without crashing.
I prefer returning an empty result over pretending a document has navigation information that it does not.
That is a small detail, but it makes file tools more predictable.
I build browser-based PDF tools at pocketpdf.site.
2.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.