= PDF Outline
:description: The title and section level depth of the PDF outline can be customized.

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.

[#title]
== 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.

[,asciidoc]
----
= The Intrepid & Thrilling Chronicles
:outline-title: The Chronicles <.>
----
<.> 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".

[#levels]
== 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.

[,asciidoc]
----
= Document Title
:outlinelevels: 3 <.>
----
<.> 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.

[,asciidoc]
----
= Document Title
:outlinelevels: 3: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.

[,asciidoc]
----
= Document Title
:outlinelevels: 1 <.>

== Section title

Content.

[outlinelevels=2] <.>
== Section title

Content.

=== Section title <.>
----
<.> 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.
<.> 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.
<.> 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]
== 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`.

.Unset outline
[,asciidoc]
----
= Document Title
:!outline: <.>
----
<.> 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.
