add clarification about outline-title attribute

asciidoctor · Jan 3, 2024 · 786e028 · 786e028
1 parent 764be7a
commit 786e028
Showing 1 changed file with 4 additions and 1 deletion.
diff --git a/docs/modules/ROOT/pages/pdf-outline.adoc b/docs/modules/ROOT/pages/pdf-outline.adoc
@@ -8,8 +8,9 @@ The outline can also be deactivated with the `outline` attribute.
 [#title]
 == outline-title attribute
 
-By default, the document title is displayed as the title of the PDF outline.
+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]
 ----
@@ -20,6 +21,8 @@ You can customize the outline title using the `outline-title` document attribute
 
 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