Outlines

Outlines (sometimes also called bookmarks) are shown in a the PDF viewer aside of the page, allowing for navigation within the document.

Creating outlines

Outlines can be created from scratch, e.g. when assembling a set of PDF files into a single document.

The following example adds outline entries referring to the 1st, 3rd and 9th page of an existing PDF.

In [1]: from pikepdf import Pdf, OutlineItem

In [2]: pdf = Pdf.open('document.pdf')

In [3]: with pdf.open_outline() as outline:
   ...:     outline.root.extend([
   ...:         # Page counts are zero-based
   ...:         OutlineItem('Section One', 0),
   ...:         OutlineItem('Section Two', 2),
   ...:         OutlineItem('Section Three', 8)
   ...:     ])
   ...: 

In [4]: pdf.save('document_with_outline.pdf')

Another example, for automatically adding an entry for each file in a merged document:

In [5]: from glob import glob

In [6]: pdf = Pdf.new()

In [7]: page_count = 0

In [8]: with pdf.open_outline() as outline:
   ...:     for file in glob('*.pdf'):
   ...:         src = Pdf.open(file)
   ...:         oi = OutlineItem(file, page_count)
   ...:         outline.root.append(oi)
   ...:         page_count += len(src.pages)
   ...:         pdf.pages.extend(src.pages)
   ...: 

In [9]: pdf.save('merged.pdf')

Editing outlines

Existing outlines can be edited. Entries can be moved and renamed without affecting the targets they refer to.

Destinations

Destinations tell the PDF viewer where to go when navigating through outline items. The simplest case is a reference to a page, together with the page location, e.g. Fit (default). However, named destinations can also be assigned.

The PDF specification allows for either use of a destination (Dest attribute) or an action (A attribute), but not both on the same element. OutlineItem elements handle this as follows:

  • When creating new outline entries passing in a page number or reference name, the Dest attribute is used.

  • When editing an existing entry with an assigned action, it is left as-is, unless a destination is set. The latter is preferred if both are present.

Creating a more detailed destination with page location:

In [10]: oi = OutlineItem('First', 0, 'FitB', top=1000)

The above will call make_page_destination when saving to a Pdf document, roughly equivalent to the following:

In [11]: oi.destination = make_page_destination(pdf, 0, 'FitB', top=1000)

Outline structure

For nesting outlines, add items to the children list of another OutlineItem.

In [12]: with pdf.open_outline() as outline:
   ....:     main_item = OutlineItem('Main', 0)
   ....:     outline.root.append(main_item)
   ....:     main_item.children.append(OutlineItem('A', 1))
   ....: