How to add bookmarks to a PDF document on Linux

Last updated on July 22, 2020 by Dan Nanni

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

In the above, /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.

Support Xmodulo

This website is made possible by minimal ads and your gracious donation via PayPal or credit card

Please note that this article is published by under a Creative Commons Attribution-ShareAlike 3.0 Unported License. If you would like to use the whole or any part of this article, you need to cite this web page at as the original source.

Xmodulo © 2021 ‒ AboutWrite for UsFeed ‒ Powered by DigitalOcean