class HexaPDF::Type::Outline


Represents the root of the PDF’s document outline containing a hierarchy of outline items (sometimes called bookmarks) in a linked list.

The document outline usually contains items for the sections of the document, so that clicking on an item opens the page where the section starts (the section header is). Most PDF viewers are able to display the outline to aid in navigation, though not all apply the optional attributes like the text color.

The outline dictionary is linked via the /Outlines entry from the Type::Catalog and can directly be accessed via HexaPDF::Document#outline.


Here is an example for creating an outline:

doc =
5.times { doc.pages.add }
doc.outline.add_item("Section 1", destination: 0) do |sec1|
  sec1.add_item("Page 2", destination: doc.pages[1])
  sec1.add_item("Page 3", destination: 2)
  sec1.add_item("Section 1.1", text_color: "red", flags: [:bold]) do |sec11|
    sec11.add_item("Page 4", destination: 3)

Here is one for copying the complete outline from one PDF to another:

doc =[0])
target =
stack = [target.outline]
doc.outline.each_item do |item, level|
  if stack.size < level
    stack << stack.last[:Last]
  elsif stack.size > level
    (stack.size - level).times { stack.pop }
# Copying all the pages so that the references work.
doc.pages.each {|page| target.pages << target.import(page) }

See: PDF2.0 s12.3.3

Field Definitions

NameType/Allowed ValuesRequiredDefault Value
FirstHexaPDF::Type::OutlineItem or Hashfalsenil
LastHexaPDF::Type::OutlineItem or Hashfalsenil

Public Instance Methods

add_item(title, **options, &block)

Adds a new top-level outline item.

See OutlineItem#add_item for details on the available options since this method just passes all arguments through to it.

each_item {|item| block } → item
each_item → Enumerator

Iterates over all items of the outline.

The items are yielded in-order, yielding first the item itself and then its descendants.