Adding Bookmarks to PDF Documents with pdfmark

Applies To: PDF Manipulation

Have you ever needed to add those fancy navigational elements to a PDF document? Some people (incorrectly) call these the table of contents, most interfaces call them Bookmarks and internally they’re collectively known as the outline. I’m talking about these things:

Bookmarks

But what if you’re generating PDFs programatically? For instance, you are converting a bunch of image files to a PDF using something like ImageMagick (or even GraphicsMagick). Or maybe your fancy software doesn’t add them and you need a way to get them added. Fortunately, you can add them through the somewhat obscure pdfmark interface! WOWEE!

There are several paid tools out there to do this and there are even some free ones that do an okay job. For instance, jpdfbookmarks is free and does an alright job (the bookmarks are there, but other PDF processors will likely mark the PDF as invalid and “repair” these by removing them). However, these often introduce an extra interface or simplified format that may not fully support everything you can do with bookmarks (let alone the rest of pdfmark). There is actually a ton you can do (even bookmarks can do far more than just navigate to another page) and the syntax isn’t that complicated.

Anatomy of a PDF Bookmark

Generally, a basic bookmark simply jumps to a specific page. Here’s a very basic example of a bookmark that will open page 2 of a PDF document (pages start at 1) with a child bookmark that will open page 3:

[ /Title (Some Bookmark)
  /Page 2
  /Count 1
  /View [/XYZ null null 0]
  /OUT pdfmark

    [ /Title (Sub Bookmark)
      /Page 3
      /View [/Fit]
      /OUT pdfmark

The whitespace (tabs and spaces) makes no difference, but I find it easier to indent child bookmarks. Here’s what’s happening:

  • represents the start of a new pdfmark “command” (you can have multiple commands in a single file)
  • /Title defines the text of the bookmark (everything in the parenthesis)
  • /Count indicates the number of child bookmarks
    • When the number is positive the bookmark is expanded (it’s children showing by default)
    • When the number is negative the bookmark is collapsed (it’s children hidden by default)
    • If there are no children, leave it out
    • Child bookmarks should follow their parent. When the children are done, the next bookmark belongs to the parent level
  • /Page defines which page number (starting with 1) to navigate to (this is not required since bookmarks can do other actions as well – see below)
  • /View defines the zoom level the destination page will have (see below for details)
  • /OUT pdfmark defines the “command” as a bookmark (/OUT) and is the end of the “command”

View Magnification

The zoom level of the destination page is set using the /View option. There are a ton of options here (see page 11 of the Cooking up Enhanced PDF with pdfmark Recipes eBook by Lynn Mead for more examples). But here are the most common values:

  • [/Fit] – Fits the page to the window (the whole page is visible)
  • [/FitH top] – Fits the width of the page to the window, replace top with a number
    • The top value is the distance from the page origin to the top of the window (offset) e.g. [/FitH 32]
  • [/FitH -32768] – Fits the width of the page to the window (top value is automatic)
  • [/FitV left] – Fits the height of the page to the window, replace left with a number
    • The left value is the distance in from the page origin to the left edge of the window (offset) e.g. [/FitV -17]
  • [/XYZ left top zoom] – Gives a specific origin offset and zoom level, replace left, top, and zoom with either a number or the word null e.g. [/XYZ 3 5 10] or [/XYZ null null 0]
    • The left value is the distance in from the page origin to the left edge of the window (offset)
    • The top value is the distance from the page origin to the top of the window (offset)
    • The zoom level is the magnification (0-100)

To simply keep whatever zoom level the user is using just use [/XYZ null null 0].

Other Options

There are additional parameters for bookmarks that can be added as necessary:

  • /Color [R G B] – Defines the color of the bookmark. Replace R, G, and B with numbers e.g. [.2 1 .76]
    • R is the percentage of Red from 0 to 1 (use decimals for other values)
    • G is the percentage of Green from 0 to 1 (use decimals for other values)
    • B is the percentage of Blue from 0 to 1 (use decimals for other values)
  • /F format – Defines the format of the bookmark text. Replace format with one of the following numbers:
    • 0 – normal
    • 1 – italic
    • 2 – bold
    • 3 – bold italic

Advanced Actions

A bookmark can do more than just open a page within the document. You can use the following parameters to change that behavior:

  • /File (filename) – Opens the PDF document specified in the filename value
    • To open a non-PDF file use the /File parameter along with /Action /Launch
  • /URI (address) – Opens the web page specified in the address value
  • /Action various – Performs an advanced action
    • There are several of these and they can get rather complicated but here’s a brief list:
      • /Action /Launch – Opens non-PDF files, requires a /File parameter
      • /Action << /Subtype /Name /N /menuitem >> – Executes the menu item specified (replace menuitem with the name of the menu item e.g. /Action << /Subtype /Name /N /Print >>)
      • /Action /Article – Follow an Article Thread (requires the /Dest parameter and optionally a /File parameter)
      • /Action << /Subtype /ImportData /F (filename.fdf) >> – Import Form Data from the specified file
      • /Action << /Subtype /ResetForm >> – Reset the Form

There are even additional actions for playing movies and sounds, executing JavaScript, and submitting form data.

See page 12 of the Cooking up Enhanced PDF with pdfmark Recipes eBook by Lynn Mead for more examples and details.

Applying the Bookmarks to a PDF Document

As a reminder, pdfmark is just put in a text file and then applied using GhostScript with the following command:

gswin64c -o [outputfilename] -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress [originalPDFfilename] [pdfmarkfillename]

For additional details about how to get this all quickly setup, see my previous post Applying pdfmark to PDF Documents Using GhostScript.

If you’re adding bookmarks, you should probably ensure they’re visible when the document is opened by also setting the View Options.

Setting PDF View Options with pdfmark

Applies To: PDF Manipulation

Using the pdfmark syntax, you can add a lot of features to existing PDF documents. In a previous post I showed you how to apply pdfmark to PDF documents using GhostScript from the command line. In this post, I’ll show you how to set the View Options using this same technique.

View Options control the default display for a PDF document when it is opened. You are able to set the zoom levels, the starting page, and determine what features of the interface are already visible.

The following pdfmark will apply View Options to a PDF document:

[ /PageMode /UseOutlines
  /Page 1
  /View [/Fit]
  /DOCVIEW pdfmark

Here’s a breakdown of what’s happening:

  • represents the start of a new pdfmark “command” (you can have multiple commands in a single file)
  • /PageMode defines the page mode display (see table below for options)
  • /Page defines which page number (starting with 1) to start on
  • /View defines the zoom level the document will start with (see below for details)
  • /DOCVIEW pdfmark defines the “command” as View Options (/DOCVIEW) and is the end of the “command”

Page Modes

The /PageMode option determines the starting state for the PDF document. None of the options disable any features (so a user can still turn them on in the interface).

  • /UseNone – Document displays without bookmarks or thumbnails visible
  • /UseOutlines – Document displays with the bookmarks visible
  • /UseThumbs – Document displays with the thumbnails visible
  • /FullScreen – Document displays in full screen mode

View Magnification

The starting zoom level for a PDF document is set using the /View option. There are a ton of options here (see page 11 of the Cooking up Enhanced PDF with pdfmark Recipes eBook by Lynn Mead for more examples). But here are the most common values:

  • [/Fit] – Fits the page to the window (the whole page is visible)
  • [/FitH top] – Fits the width of the page to the window, replace top with a number
    • The top value is the distance from the page origin to the top of the window (offset) e.g. [/FitH 32]
  • [/FitH -32768] – Fits the width of the page to the window (top value is automatic)
  • [/FitV left] – Fits the height of the page to the window, replace left with a number
    • The left value is the distance in from the page origin to the left edge of the window (offset) e.g. [/FitV -17]
  • [/XYZ left top zoom] – Gives a specific origin offset and zoom level, replace left, top, and zoom with either a number or the word null e.g. [/XYZ 3 5 10] or [/XYZ null null 0]
    • The left value is the distance in from the page origin to the left edge of the window (offset)
    • The top value is the distance from the page origin to the top of the window (offset)
    • The zoom level is the magnification (0-100)

Applying the View Options to a PDF Document

As a reminder, pdfmark is just put in a text file and then applied using GhostScript with the following command:

gswin64c -o [outputfilename] -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress [originalPDFfilename] [pdfmarkfillename]

For additional details about how to get this all quickly setup, see my previous post Applying pdfmark to PDF Documents Using GhostScript.