Generate a PDF table of contents from bookmarks

Supply the bookmarks in document order, including each title, its one-based destination page, and an optional nesting level. The generator preserves that hierarchy with indentation, adds readable dot leaders, and returns both structured entries and ready-to-use page text. Empty outlines are rejected because a contents page without entries would conceal a missing extraction or preparation step.

Prepare the bookmark outline

Start with the outline already extracted from the PDF. Each entry needs a title and a one-based page number, and entries should appear in the same order in which readers encounter them. Add a level when the bookmark belongs beneath a chapter or another parent entry; level zero represents a top-level destination, level one is indented once, and deeper non-negative levels create further indentation. The generator does not inspect or modify PDF bytes, infer bookmarks from page text, or reorder the outline. That separation keeps the result predictable and makes data problems visible. Trim misleading whitespace before submission if possible, although repeated spaces and line breaks inside titles are normalized automatically. Titles must contain visible text, page numbers must be positive integers, and levels must stay within the documented range. An empty outline produces an input error rather than a blank page, which helps automation detect PDFs whose bookmarks were absent or lost during an earlier processing stage.

Understand the generated page

The result includes a heading, a normalized array of entries, an entry count, and a page field containing the rendered text. Every rendered line starts with indentation derived from the bookmark level, continues with the cleaned title, and ends with the page number. Dot leaders fill the space between title and number to make scanning easier. The formatter uses a stable target width, but it never truncates a long title merely to preserve alignment; when a title is long, it retains the full wording and inserts a minimum leader. This behavior protects meaningful chapter names and keeps output deterministic across the browser and API. The structured entries repeat the title, page, level, and final rendered line, so a caller can use the supplied page directly or apply its own typography later. The optional heading defaults to “Table of Contents” and can be replaced with another non-empty single-line label when a publication uses different editorial wording.

Place it into a PDF workflow

Use the returned page text as the content source for the stage that creates or inserts a physical PDF page. This capability deliberately focuses on rendering the outline, so it does not rewrite page destinations after insertion, choose fonts, paginate a long contents list, or add the page to the source file. If inserting a new page shifts destination numbers, adjust the supplied page values before generating the final contents text, or perform the update in the assembly step. Keeping those responsibilities explicit prevents the common off-by-one error caused by adding front matter after bookmark pages have already been recorded. For repeatable publishing, extract or maintain the bookmark outline, validate destination pages, generate the contents page, and then pass the result into the PDF composition stage. The same deterministic logic runs without network access or stored state, which makes it appropriate for browser checks, build pipelines, document portals, and regression fixtures where identical input must always produce identical page text.