document outline attributes (PR #2146)

6 files changed, 90 insertions, 13 deletions

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 6ac4591d..53b40960 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -19,6 +19,7 @@
 * xref:notitle.adoc[]
 * xref:title-page.adoc[]
 * xref:toc.adoc[]
+* xref:pdf-outline.adoc[]
 * xref:index-catalog.adoc[]
 * xref:page-numbers.adoc[]
 * xref:asciidoc-attributes.adoc[]
diff --git a/docs/modules/ROOT/pages/asciidoc-attributes.adoc b/docs/modules/ROOT/pages/asciidoc-attributes.adoc
index 54b3687e..3b3ff9e5 100644
--- a/docs/modules/ROOT/pages/asciidoc-attributes.adoc
+++ b/docs/modules/ROOT/pages/asciidoc-attributes.adoc
@@ -1,11 +1,12 @@
-= Theme-Related AsciiDoc Attributes
+= AsciiDoc Attributes for PDF
+//Theme-Related AsciiDoc Attributes
 
-There are various settings in the theme you control using document attributes.
+There are AsciiDoc document attributes you can set in your document to control the PDF media, mode, and outline, as well as theme-related attributes for the covers, title page, and background images, and more.
 
 == AsciiDoc document attributes
 
 If an attribute is marked as "Header Only", it only takes effect if defined in the AsciiDoc document header or via the API.
-If an attribute matches a key in the theme file, the attribute takes precedence.
+If an attribute matches a key in the theme file, the document attribute takes precedence.
 
 [cols="2,3,^1,6a"]
 |===
@@ -27,7 +28,7 @@ If an attribute matches a key in the theme file, the attribute takes precedence.
 |Yes
 |`:hyphens: de`
 
-|`icons`^[13]^
+|`icons`^[12]^
 |`font` {vbar} image (default: _not set_)
 |No
 |`:icons: font`
@@ -52,12 +53,17 @@ If an attribute matches a key in the theme file, the attribute takes precedence.
 |Yes
 |`:optimize: prepress`
 
-|`outline-title`
+|xref:pdf-outline.adoc[outline]
+|flag (default: _set_)
+|Yes
+|`:outline:`
+
+|xref:pdf-outline.adoc#title[outline-title]
 |flag {vbar} String (default: _set_)
 |Yes
 |`:outline-title: Outline`
 
-|`outlinelevels`^[12]^
+|xref:pdf-outline.adoc#levels[outlinelevels]
 |Integer {vbar} Integer:Integer (default: same as _toclevels_)
 |Yes
 |`:outlinelevels: 2`
@@ -172,9 +178,7 @@ For more fine-grained control, you should customize using the theme.
 10. The title page is only enabled by default for the book doctype.
 To force the title page to be used for other doctypes, set the `title-page` attribute in the document header.
 11. If the TOC overlaps the first page of content, increase this number.
-12. The second number in the value of `outlinelevels` is the number of levels of the outline to expand (e.g., `3:1`).
-If the second number is not present, all levels are expanded.
-13. By default, admonitions have a text-based label that matches the admonition type.
+12. By default, admonitions have a text-based label that matches the admonition type.
 To use icons instead, set the `icons` attribute to `font`.
 This setting allows the theme to control the icon used for each type (see the xref:theme:admonition.adoc#icon-name[admonition-icon key]).
 It also enables the `icon` macro (covered in the README).
diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc
index cdaa6cf2..13726a8b 100644
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/docs/modules/ROOT/pages/features.adoc
@@ -11,7 +11,7 @@
 * Front and back cover pages
 * Title page
 * Document metadata (title, authors, subject, keywords, etc.)
-* PDF document outline
+* xref:pdf-outline.adoc[PDF document outline]
 * xref:toc.adoc[Table of contents with page numbers]
 * Configurable page size (e.g., A4, Letter, Legal, etc.) and layout (portrait or landscape)
 * Internal cross reference links
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.
diff --git a/docs/modules/ROOT/pages/toc.adoc b/docs/modules/ROOT/pages/toc.adoc
index f621837c..29345a2e 100644
--- a/docs/modules/ROOT/pages/toc.adoc
+++ b/docs/modules/ROOT/pages/toc.adoc
@@ -24,10 +24,10 @@ For documents that have the `book` doctype, the TOC is inserted using discrete p
 For all other doctypes, unless the `title-page` attribute is set, the TOC is inserted in the flow of text.
 If a placement is not specified, that location is between the document title and the first block of content.
 
-While the table of contents isn't generated by default, the PDF outline is always included.
+While the table of contents isn't generated by default, the PDF outline is always generated.
 The `toclevels` attribute controls the depth of both the TOC and the PDF outline, regardless of whether the TOC is enabled.
-The depth of the outline can be controlled independently using the `outlinelevels` attribute.
-Both attributes can also be set on individual sections to override the depth for a given section and its children.
+The depth of the PDF outline can be controlled independently using the xref:pdf-outline.adoc#levels[outlinelevels attribute].
+//Both attributes can also be set on individual sections to override the depth for a given section and its children.
 
 == Insert TOC entries
 
diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 681ffd1b..139dba8e 100644
--- a/docs/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -133,6 +133,11 @@ The `callout-list` category includes the `margin-top-after-code` key that can co
 Caption end:: You can now configure whether the caption for a block image is placed above or below the image using the `caption-end` theme key.
 See xref:theme:block-image.adoc#caption[Block Image Category Keys] for the list of available `image-caption` theme keys and their value types.
 
+== PDF outline
+
+PDF outline title and levels:: You can now deactivate the PDF outline by unsetting the `outline` document attribute (`:!outline:`) as well as customize its title with `outline-title` and the section level depth and expansion with `outlinelevels`.
+See xref:pdf-outline.adoc[] for details.
+
 == Running content and page numbering
 
 xref:theme:add-running-content.adoc#start-at[Select the page where running content starts]:: Specify the page on which the running content starts being displayed by assigning an integer to the `start-at` theme key on the `running-content` category.