`update_bookmarks`

Replace PDF bookmarks from a YAML or JSON file

Usage

pdftl <input> update_bookmarks <bookmarks_file> output <filename>

Details

Replaces the document’s Table of Contents (bookmarks) entirely using a specified YAML or JSON file, or YAML data on stdin if bookmarks_file is set to “-“.

This operation consumes the structured format generated by the dump_bookmarks command. It applies strict validation to prevent broken PDFs: it validates page boundaries, catches typos in property names, and ensures the hierarchical tree structure is sound.

Important Rules & Behaviors

Full Replacement: This command does not merge or append bookmarks. It completely overwrites the existing Table of Contents with the contents of your file.
Page Indexing: Target page numbers must be 1-indexed (e.g., page: 1 points to the very first physical page of the document).
Boundary Checking: If a bookmark points to a page number that exceeds the total number of pages in the PDF, the operation will fail safely to prevent document corruption.
Strict Validation: Unrecognized properties (such as a typoed pagee instead of page) will trigger an error rather than being silently ignored. This ensures your routing logic always behaves as expected.

Clearing Bookmarks

If you want to completely remove the Table of Contents from a PDF, you can provide a file containing just an empty list.

YAML file content: []
JSON file content: []

Dependency note

Loading YAML files requires the pyyaml library. If it is not installed, you can install it via pip install pdftl[yaml-bookmarks], or simply use .json files natively.

Examples

Apply a YAML bookmarks file

pdftl in.pdf update_bookmarks bookmarks.yaml output modified.pdf

Apply a JSON bookmarks file

pdftl in.pdf update_bookmarks bookmarks.json output modified.pdf

Tags: info, metadata, bookmarks

Source: pdftl.operations.update_bookmarks

Read online: https://pdftl.readthedocs.io/en/stable/operations/update_bookmarks.html

Type: Operation

update_bookmarks