PDF Outline
Asciidoctor PDF generates a PDF outline by default.
You can customize the outline title and the depth of section levels that are displayed in the PDF outline using AsciiDoc document attributes.
The outline can also be deactivated with the outline attribute.
outline-title attribute
By default, the document title is displayed as the first entry in the PDF outline.
You can customize the outline title using the outline-title document attribute.
If this attribute is set and the value is not empty, it gets used instead of the document title.
= The Intrepid & Thrilling Chronicles
:outline-title: The Chronicles (1)| 1 | Set outline-title in the document header and assign it your preferred title for the PDF outline. |
The PDF outline resulting from the example above will be titled “The Chronicles”.
If you plan to override this entry for a batch of documents, you may want to use a generic term such as "Outline", "Title Page" (when the doctype is book), or "Contents".
outlinelevels attribute
You can adjust the depth of section levels that are displayed in the PDF outline independent of the TOC level depth using the outlinelevels document attribute.
By default, outlinelevels attribute is set to the same value as toclevels and all the levels are fully expanded.
To customize the depth of the section levels displayed in the PDF outline and configure them to be expanded, set the outlinelevels attribute in the header of your document and assign it an integer.
= Document Title
:outlinelevels: 3 (1)| 1 | Set outlinelevels in the document header and assign it an integer.
Accepted numbers are 1 through 5. |
In the above example, outlinelevels is set to 3.
The resulting PDF outline will list the part titles (if present and the doctype is book), level 1 (==), level 2 (===), and level 3 (====) section titles.
All the parts and sections listed in the PDF outline will be fully expanded because a second number isn’t present in the value assigned to outlinelevels.
To specify which levels are automatically expanded in the PDF outline, set the outlinelevels attribute in the header of your document and assign it a two-integer value (e.g., 4:1).
The first number represents the section level depth included in the outline; the second number represents the level depth after which the levels are no longer automatically expanded.
= Document Title
:outlinelevels: 3:1 (1)| 1 | Directly after the first integer, enter a colon (:), and then a second integer. |
You can also override the outlinelevels document attribute for a specific section and its children by setting outlinelevels on the section’s parent.
= Document Title
:outlinelevels: 1 (1)
== Section title
Content.
[outlinelevels=2] (2)
== Section title
Content.
=== Section title (3)| 1 | The outlinelevels document attribute is set to 1.
The resulting PDF outline will list the part titles (if present and the doctype is book) and level 1 (==) section titles. |
| 2 | Set outlinelevels on the parent section title that will already be listed in the PDF outline due to the global outlinelevels value.
Assign the outlinelevels on the section title the numeric value of the next section level you want to be inserted into the PDF outline. |
| 3 | This section title (and any of its children) will be listed in the PDF outline because [outlinelevels=2] was assigned to its parent section title. |
Deactivate the outline
The PDF outline is generated by default when you run Asciidoctor PDF.
You can turn off the outline by unsetting the document attribute outline.
= Document Title
:!outline: (1)| 1 | Unset the outline attribute by prefixing it with the bang symbol (!). |
When the outline attribute is unset, the resulting PDF won’t have an outline.