Chapter 6
Bookmarks

cpdf -list-bookmarks [-utf8 | -raw] in.pdf

cpdf -list-bookmarks-json in.pdf

cpdf -remove-bookmarks in.pdf -o out.pdf

cpdf -add-bookmarks <bookmark file> in.pdf -o out.pdf

cpdf -add-bookmarks-json <bookmark file> in.pdf -o out.pdf

cpdf -bookmarks-open-to-level <n> in.pdf -o out.pdf

cpdf -table-of-contents [-toc-title] [-toc-no-bookmark]
     [-font <font>] [-font-size <size>] in.pdf -o out.pdf

PDF bookmarks (properly called the document outline) represent a tree of references to parts of the file, typically displayed at the side of the screen. The user can click on one to move to the specified place. cpdf provides facilities to list, add, and remove bookmarks. The format used by the list and add operations is the same, so you can feed the output of one into the other, for instance to copy bookmarks.

6.1 List Bookmarks

The -list-bookmarks operation prints (to standard output) the bookmarks in a file. The first column gives the level of the tree at which a particular bookmark is. Then the text of the bookmark in quotes. Then the page number which the bookmark points to. Then (optionally) the word ”open” if the bookmark should have its children (at the level immediately below) visible when the file is loaded. Then the destination (see below). For example, upon executing

cpdf -list-bookmarks doc.pdf

the result might be:

0 "Part 1" 1 open
1 "Part 1A" 2 "[2 /XYZ 200 400 null]"
1 "Part 1B" 3
0 "Part 2" 4
1 "Part 2a" 5

If the page number is 0, it indicates that clicking on that entry doesn’t move to a page.

By default, cpdf converts unicode to ASCII text, dropping characters outside the ASCII range. To prevent this, and return unicode UTF8 output, add the -utf8 option to the command. To prevent any processing, use the -raw option. See Section 1.17 for more information. A newline in a bookmark is represented as "\n".

By using -list-bookmarks-json instead, the bookmarks are formatted as a JSON array, in order, of dictionaries formatted thus:

{ "level": 0,
  "text": "1 Basic Usage",
  "page": 17,
  "open": false,
  "target":
    [ { "I": 17 },
      { "N": "/XYZ" },
      { "F": 85.039 },
      { "F": 609.307 },
      null ]
}

See chapter 15 for more details of cpdf’s JSON formatting. Bookmark text in JSON bookmarks, however, is in UTF8 for ease of use.

6.1.1 Destinations

The destination is an extended description of where the bookmark should point to (i.e it can be more detailed than just giving the page). For example, it may point to a section heading halfway down a page. Here are the possibilities:

-F[por/mXaYtZ-lefttopzoom]-------DD-eisscprliapytiopnage n-umber-p------------------------
                          at u pper-left of w indow and magn ification of zoom.
                          W riting“null” for anyofleft,topor zoom specifiesn o
                          change. A zoom of0isthesam eas“nu ll”.
 [p /Fit]                   D isplay p age num ber p so as to fit fully within the
                          w in dow.
 [p /FitH top]              D isplay page num ber p with vertical coord inate to
                          at the top of th e w ind ow and the page m agnifi ed
                          so its width fits the window . A null value for top
                          im pliesno ch an ge.
 [p /FitV left]               D isplay p age num ber p w ith ho rizontal coordinat
                          leftattheleftofthew ind ow,and the pagem agnifi ed
                          so its h eight fi ts the w indo w. A null valu e for left
                          im pliesno ch an ge.
 [p /FitR leftbottom righttop]  D isplay page n umber p magnified so &#x
                          tirelyw ithintherectanglespecifiedby theotherpa-
                          ram eters.
 [p /FitB]                  A s for /F it bu t with the page’s bounding box (see
                          below).
 [p /FitBH top]             A sfor/FitH bu twith thepage’sbound ing box(see
                          below).
 [p /FitBV left]             A s for /FitV but with the page’s bound ing box (se
                          below).

The bounding box is the intersection of the page’s crop box and the bounding box of the page contents. Some other kinds of destination may be produced by -list-bookmarks. They will be preserved by -add-bookmarks and may be edited as your risk.

6.2 Remove Bookmarks

The -remove-bookmarks operations removes all bookmarks from the file.

cpdf -remove-bookmarks in.pdf -o out.pdf

6.3 Add Bookmarks

The -add-bookmarks file adds bookmarks as specified by a bookmarks file, a text file in ASCII or UTF8 encoding and in the same format as that produced by the -list-bookmarks operation. If there are any bookmarks in the input PDF already, they are discarded. For example, if the file bookmarks.txt contains the output from -list-bookmarks above, then the command

cpdf -add-bookmarks bookmarks.txt in.pdf -o out.pdf

adds the bookmarks to the input file, writing to out.pdf. An error will be given if the bookmarks file is not in the correct form (in particular, the numbers in the first column which specify the level must form a proper tree with no entry being more than one greater than the last).

Bookmarks in JSON format (see above) may be added with -add-bookmarks-json:

cpdf -add-bookmarks-json bookmarks.json in.pdf -o out.pdf

Remember that strings in JSON bookmark files are in UTF8, rather than as native PDF strings.

6.4 Opening bookmarks

As an alternative to extracting a bookmark file and manipulating the open-status of bookmarks, mass manipulation may be achieved by the following operation:

cpdf -bookmarks-open-to-level <level> in.pdf -o out.pdf

A level of 0 will close all bookmarks, level 1 will open just the top level, closing all others etc. To open all of them, pick a sufficiently large level.

6.5 Making a Table of Contents

Cpdf can automatically generate a table of contents from existing bookmarks, adding it to the beginning of the document.

cpdf -table-of-contents in.pdf -o out.pdf

The page(s) added will have the same dimensions, media and crop boxes as the first page of the original file. The default title is “Table of Contents”, though this may be changed:

cpdf -table-of-contents -toc-title "Contents" in.pdf -o out.pdf

An empty title removes the title. The sequence \n may be used to split the title into lines. The default font is 12pt Times Roman (and 24pt for the title). The base font and size may be changed with -font and -font-size (see chapter 8 for full details):

cpdf -table-of-contents -font "Courier-Bold" -font-size 8
        in.pdf -o out.pdf

By default, an entry for the new table of contents will be added to the document’s bookmarks. To suppress this behaviour, add -toc-no-bookmark:

cpdf -table-of-contents -toc-no-bookmark in.pdf -o out.pdf

Java Interface

 
/* CHAPTER 6. Bookmarks */ 
 
/** Starts the bookmark retrieval process for a given PDF. */ 
public native void startGetBookmarkInfo(Pdf pdf) throws CpdfError; 
 
/** Gets the number of bookmarks for the PDF given to {@link 
#startGetBookmarkInfo(Pdf) startGetBookmarkInfo}. */ 
public native int numberBookmarks() throws CpdfError; 
 
/** Gets the bookmark level for the given bookmark 
<code>0...(n - 1)</code>. */ 
public native int getBookmarkLevel(int serial) throws CpdfError; 
 
/** Gets the bookmark target page for the given PDF (which must be the 
same as the PDF passed to  {@link #startGetBookmarkInfo(Pdf) 
startGetBookmarkInfo}) and bookmark <code>0...(n - 1)</code>. */ 
public native int getBookmarkPage(Pdf pdf, int serial) throws CpdfError; 
 
/** Returns the text of bookmark <code>0...(n - 1))</code> */ 
public String getBookmarkText(int serial) throws CpdfError; 
 
/** Returns <code>true</code> if the bookmark is open. */ 
public native boolean getBookmarkOpenStatus(int serial) throws CpdfError; 
 
/** Ends the bookmark retrieval process, cleaning up. */ 
public native void endGetBookmarkInfo() throws CpdfError; 
 
/** Starts the bookmark setting process for n bookmarks. */ 
public native void startSetBookmarkInfo(int n) throws CpdfError; 
 
/** Set bookmark level for the given bookmark <code>0...(n - 1)</code>. */ 
public native void setBookmarkLevel(int serial, int level) 
    throws CpdfError; 
 
/** Sets the bookmark target page for the given PDF (which must be the same 
as the PDF to be passed to {@link #endSetBookmarkInfo(Pdf) 
endSetBookmarkInfo}) and bookmark <code>0...(n - 1)</code>. */ 
public native void setBookmarkPage(Pdf pdf, int serial, int pagenum) 
    throws CpdfError; 
 
/** Sets the open status of bookmark <code>0...(n - 1)</code>. */ 
public native void setBookmarkOpenStatus(int serial, boolean open) 
    throws CpdfError; 
 
/** Sets the text of bookmark <code>0...(n - 1)</code>. */ 
public void setBookmarkText(int serial, String text) throws CpdfError; 
 
/** Ends the bookmark setting process, writing the bookmarks to the given 
PDF. */ 
public native void endSetBookmarkInfo(Pdf pdf) throws CpdfError; 
 
/** Returns the bookmark data in JSON format. */ 
public native byte[] getBookmarksJSON(Pdf pdf) throws CpdfError; 
 
/** Sets the bookmarks from JSON bookmark data. */ 
public native void setBookmarksJSON(Pdf pdf, byte[] data) throws CpdfError; 
 
/** Typesets a table of contents from existing bookmarks and prepends it to 
the document. 
@param pdf PDF document 
@param font font, such as {@link #timesRoman timesRoman} 
@param fontsize font size 
@param title table of contents title 
@param bookmark if <code>true</code>, the table of contents gets its own 
bookmark. */ 
public void tableOfContents(Pdf pdf, int font, double fontsize, 
                            String title, boolean bookmark) 
    throws CpdfError;