List PDF bookmarks

Each returned item contains the bookmark title, its one-based nesting level, and its one-based target page. The traversal preserves the document’s outline order and places every child immediately after its parent. Empty outlines are rejected explicitly, so a missing table of contents cannot be mistaken for a successful result with no data.

Convert a nested outline into practical rows

PDF bookmarks are usually represented as an outline tree. Chapters sit at the top level, sections appear below chapters, and deeper headings may continue for several more levels. That structure is useful in a viewer, but it is awkward when you need to audit navigation, create a report, compare two editions, or send the information to a spreadsheet. This capability walks the outline in pre-order: it emits a parent first, then each of that parent’s descendants in their original order, before moving to the next sibling. Every output row contains only the information needed for a bookmark inventory: title, level, and target page. Levels start at one, matching how people normally describe top-level chapters, and pages are also one-based. The resulting list remains faithful to the visible reading order while removing recursive nesting. It does not open or modify a PDF file; it accepts the outline tree already obtained from a PDF parser or document-processing step.

Understand validation and deterministic ordering

Each bookmark must be an object with a non-empty title and a positive integer page. Optional children must be an array containing more bookmark objects. Whitespace around a title is removed so accidental padding does not leak into reports, but title text inside that boundary is preserved exactly. The algorithm never sorts bookmarks, because alphabetical or page-based sorting could destroy the author’s intended outline order. Instead, it follows the sequence supplied by the parser and assigns the level from the bookmark’s depth in the tree. The same input therefore always produces the same output, without network calls, timestamps, random identifiers, or environment-dependent behavior. An empty top-level outline returns an invalid-input error rather than an empty success. That distinction is useful in automation: a pipeline can stop when a document has no bookmarks instead of publishing an apparently valid, blank navigation index. Malformed child collections, missing titles, invalid page targets, excessive depth, cycles, and unreasonably large trees are rejected with focused messages.

Use the list in document workflows

A flat bookmark list works well as a boundary between PDF parsing and later business logic. You can render it as a table of contents, check that every expected chapter is present, compare titles and page destinations across document versions, or map pages to section names for downstream extraction. Because the response includes both count and ordered bookmark records, simple systems can verify the total before processing individual entries. The level value lets a consumer reconstruct indentation or rebuild a tree when necessary, while the page value supports navigation and page-range calculations. Keep in mind that this capability reports the outline it receives; it does not verify that target pages exist in a particular PDF, infer headings from page text, or repair broken destinations. Validate page bounds when the source parser provides the PDF page count. Browser execution is available for interactive work, and API requests cost $0.002 when you need repeatable automation. In both channels, the shared deterministic implementation returns the same structured result.