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

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.

  • uri=<url> Create a web link instead of an internal page destination.

  • launch=<file> Create a launch action to open an external file.

  • named=<action> Create a named action (e.g., NextPage, PrevPage).

  • dest=<name> Link to an internal named destination instead of a page number.

  • color=<r> <g> <b> Set the text color (RGB format: e.g. 1.0 0.0 0.0 for red).

  • bold=true/false

  • italic=true/false

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.

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 and styled bold

pdftl in.pdf add_bookmarks '1/{filename_base}/(position=tail, bold=true)' output out.pdf

Add an external blue URI link triggered from page 1’s iteration

pdftl in.pdf add_bookmarks '1/Website/(uri=https://example.com, color=0.0 0.5 1.0)' 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

Tags: in_place, bookmarks, outlines, add

Source: pdftl.operations.add_bookmarks

Read online: https://pdftl.readthedocs.io/en/latest/operations/add_bookmarks.html

Type: Operation