Hide Section Titles
Asciidoctor PDF adds support for the notitle option on a section as a way to express that you want the title of that section to be hidden in the document body.
This option can also be used to add a TOC entry for a preamble, anonymous preface, or imported PDF page.
notitle option
When the notitle option is set on a section, the converter will hide the section title in the body of the document, but still display it in the TOC and in cross references to that section.
To hide a section title, add the notitle option on the section.
You can set the notitle option using either the named attribute syntax, opts=notitle, or the shorthand syntax, %notitle (preferred).
The following example shows how to use the shorthand syntax.
[%notitle] (1)
== Reference Text Only
Content of section.| 1 | Assign the notitle option to the section using the shorthand percent symbol (%) for the option attribute name. |
The section is still referenceable and its title still shows up in the TOC. The title is just hidden in the document (and does not take up space).
Add a TOC entry for a preamble or anonymous preface
If a document has a preamble or an anonymous preface (i.e., preface-title is not set), there’s no reference to this content in the TOC.
For documents that depend heavily on the TOC or outline for navigation, this can cause the content to be overlooked.
To alleviate this problem, you can use the notitle option to add a TOC entry for a preface or preamble.
When notitle is set on the preface section, the title of the preface isn’t shown in the body of the document, but the title is shown in the TOC and references the preface section.
notitle on the preface section= Document Title
:doctype: book (1)
:toc:
[%notitle] (2)
== Preface
This is the preface.
== Chapter A
== Chapter B| 1 | The doctype must be book. |
| 2 | Assign the notitle option to the preface section. |
In the above example, the preface section title, “Preface”, will be displayed in the TOC, but not in the body of the document.
Alternatively, you can assign notitle to the first content block of the preamble, and assign a title to the preface-title document attribute.
notitle on first content block of preamble= Document Title
:doctype: book (1)
:preface-title: Preface (2)
:toc:
[%notitle] (3)
This is the first block of the preamble.
== Chapter A
== Chapter B| 1 | The doctype must be book. |
| 2 | Set the preface-title document attribute and assign it the title you want displayed in the TOC. |
| 3 | Assign the notitle option to the first content block of the preamble. |
In the above example, the value assigned to preface-title, “Preface”, will be displayed in the TOC and will reference the start of the preamble.
Add a TOC entry for an imported PDF
You can insert an entry for an imported PDF page anywhere in the TOC hierarchy by entering a section title prior to the import location and assigning the notitle option to the section.
[%notitle]
== Reference Card
image::reference-card.pdf[]The section title, “Reference Card”, in the above example won’t be shown in the body of the document, but it will be displayed in the TOC and reference the first page of the imported PDF.
If the doctype isn’t book and the hidden section title isn’t a part (=) or chapter (==), you may want to add a manual page break above it to ensure the anchor points to the imported page.
<<< (1)
[%notitle]
=== Reference Card
image::reference-card.pdf[]| 1 | Insert a page break (<<<) to make sure the anchor for the hidden section is kept together with the imported PDF page if the doctype isn’t book or the section isn’t a part or chapter. |