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 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.

  • Precedence: dump_bookmarks output may contain a dest field alongside resolved page and view fields. This means that the bookmark uses a named destination, and for convenience, the dump includes the resolved page number and view parameters. For update_bookmarks, the dest field, if present, always takes precedence. If both are present, a warning is issued on first encounter.

    • To update page and view, delete the dest field.

    • To avoid the warning and keep the dest field only, delete page and view. Alternatively, use the no_resolve keyword when using dump_bookmarks to avoid this issue.

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: { "bookmarks": [] }

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/latest/operations/update_bookmarks.html

Type: Operation