How to add bookmarks to a PDF document on Linux

Question: I would like to add bookmarks to a PDF file, so that the bookmarks appear in the left hand side bookmarks panel. Is there a command-line approach to create bookmarks and embed bookmark links in a PDF file on Linux?

In a PDF document, bookmarks can be added as a navigational tool to allow readers to locate and quickly move to particular sections in the document by clicking on bookmark links. If a PDF file is a very log document with hundreds of pages, adding properly organized bookmarks can be essential to guide users to browse the document effectively.

PDF bookmarks can be implemented with the pdfmark operator, which is part of a PostScript language extension. Among other things, pdfmark can be used to add a hotlink to a small piece of text in a PDF, which is pretty much a bookmark function.

pdfmark can be embedded into a PDF file with Ghostscript. Here is how to add PDF bookmarks from the command line with Ghostscript on Linux.

Add Bookmarks in a PDF file with Ghostscript

To add PDF bookmarks, first create an index file ( in the format of:

[/Page 1 /Title (January) /OUT pdfmark
[/Page 2 /Title (February) /OUT pdfmark
[/Page 3 /Title (March) /OUT pdfmark
[/Page 4 /Title (April) /OUT pdfmark
[/Page 5 /Title (May) /OUT pdfmark
[/Page 6 /Title (June) /OUT pdfmark
[/Page 7 /Title (July) /OUT pdfmark

"/Page" indicates the page number to the bookmark jumps to, and "/Title" represents the name of the bookmark.

Once you created, use the following command to add the bookmarks in the PDF file input.pdf. output.pdf will have the bookmarks embedded.

$ gs -sDEVICE=pdfwrite -q -dBATCH -dNOPAUSE -sOutputFile=output.pdf -dPDFSETTINGS=/prepress -f input.pdf

For example, given the input PDF file:

The output PDF file will look like:

Add Nested Bookmarks in a PDF file with Ghostscript

If you have a structured PDF document with chapters, sections, subsections, etc., you may want to add "nested" bookmarks in the PDF file. In that case, use "/Count N" attribute with pdfmark to represent nested levels. The argument 'N' corresponds to the number of immediately subordinate bookmarks. For example, if the first chapter has three sections, you can can add "/Count 3" in that chapter's bookmark, and if a given section has two subsections, include "/Count 2" in the section's bookmark.

Let's create nested bookmarks for the following document.

The created index file looks like the following.

[/Count 3 /Page 4 /Title (Introduction) /OUT pdfmark
[/Page 4 /Title (Features) /OUT pdfmark
[/Page 6 /Title (Mailing lists and IRC channel) /OUT pdfmark
[/Page 6 /Title (Virus submitting) /OUT pdfmark
[/Count 2 /Page 6 /Title (Base package) /OUT pdfmark
[/Count 2 /Page 6 /Title (Supported platforms) /OUT pdfmark
[/Page 6 /Title (UNIX) /OUT pdfmark
[/Page 7 /Title (Windows) /OUT pdfmark
[/Page 7 /Title (Binary packages) /OUT pdfmark
[/Count 7 /Page 7 /Title (Installation) /OUT pdfmark
[/Page 7 /Title (Requirements) /OUT pdfmark
[/Page 8 /Title (Installing on shell account) /OUT pdfmark
[/Page 8 /Title (Adding new system user and group) /OUT pdfmark
[/Page 9 /Title (Compilation of base package) /OUT pdfmark
[/Page 9 /Title (Compilation with clamav-milter enabled) /OUT pdfmark
[/Page 9 /Title (Running unit tests) /OUT pdfmark
[/Page 10 /Title (Reporting a unit test failure bug) /OUT pdfmark

Use the same command as above to add nested bookmarks in the input PDF file.

$ gs -sDEVICE=pdfwrite -q -dBATCH -dNOPAUSE -sOutputFile=output.pdf -dPDFSETTINGS=/prepress -f input.pdf

The output PDF file with nested bookmarks will look like the following.

All nested bookmarks are expanded by default. If you want nested bookmarks to be collapsed initially, use "[/Count -N]" format (i.e., add '-' sign in front of the number).

With that, the output will look like the following.

You will need to click on each closed bookmark to expand it.

Download this article as ad-free PDF (made possible by your kind donation): 
Download PDF

Subscribe to Ask Xmodulo

Do you want to receive Linux related questions & answers published at Ask Xmodulo? Enter your email address below, and we will deliver our Linux Q&A straight to your email box, for free. Delivery powered by Google Feedburner.

Support Xmodulo

Did you find this tutorial helpful? Then please be generous and support Xmodulo!

2 thoughts on “How to add bookmarks to a PDF document on Linux

  1. An actually functional way of doing this is to install Wine and download Foxit Reader for Windows (which used to be able to do add bookmarks, I presume it still can). It's not open source.

    I suggest this because the open source tools for doing this are useless.

Leave a comment

Your email address will not be published. Required fields are marked *