#  `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](https://pdftl.readthedocs.io/en/stable/operations/update_bookmarks.html)*

*Type: Operation*