document outline attributes (PR #2146)

1 files changed, 67 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/pdf-outline.adoc b/docs/modules/ROOT/pages/pdf-outline.adoc
new file mode 100644
index 00000000..4c1107d6
--- /dev/null
+++ b/docs/modules/ROOT/pages/pdf-outline.adoc
@@ -0,0 +1,67 @@
+= 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
+
+By default, the document title is displayed as the title of the PDF outline.
+You can customize the outline title using the `outline-title` document attribute.
+
+[,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`".
+
+[#levels]
+== outlinelevels
+
+You can adjust the depth of section levels that are displayed in the PDF outline independent of the TOC level depth with the `outlinelevels` document attribute.
+By default, `outlinelevels` is set to the same value as `toclevels` and all the included levels are fully expanded.
+
+To customize the depth of the section levels displayed in the PDF outline and their expansion, 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.
+
+[#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.