#  `add_bookmarks`

Add top-level bookmarks
## Usage
> pdftl `<input>` `add_bookmarks` `<spec>...` `output` `<file>` `[<option>...]`

## Details
Add one or more top-level bookmarks to a PDF.

Each `<spec>` has the format:

    <page_range><delimiter><title><delimiter>[(<options>)]

`<delimiter>` must be a single non-alphanumeric, non-parenthesis character
(e.g., `/`, `!`, `#`). The same delimiter must be used on both sides of the title.

### Page range

The page range selects which pages receive bookmarks. Each matched page gets
its own bookmark. Standard pdftl page-spec syntax applies (see `pdftl help pages`).

A bare range without a delimiter adds a bookmark pointing to page 1 using
an empty title — use the full spec form for any real usage.

### Title

The title string supports `{variable}` substitution, using the same variables
as `add_text`:

  - `{page}`           — current page number (1-based)
  - `{n}` or `{count}` — 1-based sequential counter within the matched
                         pages of the current spec
  - `{total}`          — total number of pages in the PDF
  - `{filename}`       — input filename including extension
  - `{filename_base}`  — input filename without extension
  - `{filepath}`       — full path to the input file

Variables are expanded per page: `{filename_base} p.{page}` on a 10-page
document produces ten distinct titles.

### Options

Options are comma-separated `key=value` pairs inside parentheses:

  `position=<pos>`  Where in the top-level bookmark list to insert this batch.
                    `head` — prepend before all existing bookmarks (default).
                    `tail` — append after all existing bookmarks.

No other options are currently supported, but the parenthesised syntax is
an extension point (e.g., `bold=true`, `color=...` may be added later).

### Ordering of multiple specs

All `head` specs are collected in argument order and prepended as a batch.
All `tail` specs are collected in argument order and appended as a batch.
The final outline is:

    <head batch> <existing bookmarks> <tail batch>

Within each batch, bookmarks are ordered by the sequence the page range produces
them — so a reversed range `3-1/{title}/` produces three bookmarks in the order
page 3, page 2, page 1.
## Examples

> Add a top-level bookmark for page 1 titled with the filename (prepended)
```
pdftl in.pdf add_bookmarks '1/{filename_base}/' output out.pdf
```

> Same but appended after existing bookmarks
```
pdftl in.pdf add_bookmarks '1/{filename_base}/(position=tail)' output out.pdf
```

> Add a bookmark for each of pages 1-3, titled 'Chapter N' for N=1,2,3
```
pdftl in.pdf add_bookmarks '1-3/Chapter {page}/' output out.pdf
```

> Add a bookmark for each of pages 2,5,6, titled 'Chapter N' for N=2,3,4
```
pdftl in.pdf add_bookmarks '3,5,6/Chapter {n+1}/' output out.pdf
```

> Prepend a title bookmark and append an appendix bookmark
```
pdftl in.pdf add_bookmarks '1/{filename_base}/(position=head)' '5/Appendix/(position=tail)' output out.pdf
```

> Add one bookmark per page, appended
```
pdftl in.pdf add_bookmarks '1-end/{page}: {filename_base}/(position=tail)' output out.pdf
```


**Tags**: in_place, bookmarks, outlines, add

*Source: pdftl.operations.add_bookmarks*

*Read online: [https://pdftl.readthedocs.io/en/latest/operations/add_bookmarks.html](https://pdftl.readthedocs.io/en/latest/operations/add_bookmarks.html)*

*Type: Operation*