The <bookmark> command

This command creates a PDF bookmark. It is the only way to create bookmarks when the <bookmark-properties/> command has been used to set “manual” bookmark mode.

The content of the command is used to construct the text of the bookmark, for example:

<bookmark level="2">Introduction</bookmark>

or

<bookmark style="bold"><content/></bookmark>

As for automatically-generated bookmarks, all tags are removed when constructing the bookmark text. You can use the remove option to remove the content of certain elements.

The following table lists the command options. Apart from level, the default values for options are taken from the values set by the <bookmark-properties/> command.

Option Values Description
level 1 – 9 The level at which the bookmark appears. A top-level bookmark has level one. Defaults to one if not specified.
state “open” or “closed”

A bookmark can either be open (showing its children bookmarks) or closed. This controls the open/closed state of bookmarks when the PDF is opened.

If this option is not present, the state is determined by the value of the openlevel option in the <bookmark-properties/> command.

style “normal”, “bold”, “italic” or “bolditalic” Sets the font style for bookmark text.
color A color as described in “Colors” Sets the color for bookmark text.
zoom “fit”, “fith”, “fitb”, “fitbh” or “none” Sets the page magnification set when the bookmark is activated as described below.
action “open:file-path” or “link:target-id

If no action is specified, the bookmark is a hyperlink to the current position in the document (in other words, just like an automatically-generated bookmark).

A bookmark can be used to open another file or to link to somewhere other than the current position. These options are discussed in detail below.

remove One or more tag names, separated by spaces

Each tag name specifies an element whose content is to be removed when creating the bookmark text. This does not affect text assigned to the table of contents.

For example, say you have elements called <idx1> and <idx2> that contain information to be extracted into an index. To prevent the text in these elements from appearing in bookmarks, use:

<bookmark
  remove="idx1 idx2">

Zoom values

By default activating a bookmark will display the target without changing the current page magnification (or “zoom”). An explicit zoom factor can be associated with the bookmark by setting the zoom parameter to one of the following values.

fit

Display the entire page containing the bookmark target.

fith

Show the target at the top of the window, with the magnification adjusted to show the entire page width.

fitb

As for “fit” but use the page bounding box to determine the magnification (the smallest rectangle that includes all of the page content).

fitbh

As for “fith” but use the page bounding box to determine the magnification.

Actions

If the action begins with open: the remainder is interpreted as the path to a file. This will create a bookmark that opens the specified file when clicked. If the target is a PDF file it will be opened by the PDF reader; whether other types of files can be opened successfully depends on the reader being used.

The file path can be either absolute or relative. When it is relative, it is resolved relative to the location of the originating PDF file when it is opened. This means that if PDF file “abc.pdf” has a bookmark with action “open:def.pdf”, then both abc.pdf and def.pdf must be in the same folder.

If the action begins with link: the remainder is interpreted as a target identifier. The bookmark will go to the nominated target when clicked. The link target is resolved as explained in “Creating a link”, but note that URI and URL targets are not supported for bookmark links.

When linking to a target within the current document the magnification set by the zoom parameter, if any, is used.

[Note] Note

When a bookmark links to an external PDF file via a target identifier, the external PDF will open at its first page, regardless of which page contains the target.

The action may be supplied without a prefix, in which case TopLeaf first tries to resolve it as a link target. If this fails, it assumes it is a file path. Avoid specifying actions in this way, as it is not guaranteed to work if new action types are added in the future.

[Note] Note

The action prefix “page:” was previously used to indicate the zoom factor to apply. This prefix is deprecated and may be removed in future versions. Use the zoom parameter instead.