Subtitle

An optional subtitle can be appended to a document title.

The HTML 5 converter does not distinguish the document title from the subtitle in its output. It’s only distinguished from the document title when you use the Docbook, EPUB 3, and PDF converters.

Subtitle syntax

When the document title contains a colon followed by a space (i.e, : ), the text after the final colon-space sequence is treated as a subtitle.

Example 1. A document title and subtitle

= Main Title: Subtitle

The separator is searched for from the end of the text. Therefore, only the last occurrence of the separator (i.e, : ) is used for partitioning the title.

Example 2. A document title that contains more than one colon-space sequence

= Main Title: Main Title Continued: Subtitle

Modify the title separator

You can change the title separator by specifying the separator block attribute explicitly above the document title. A space will automatically be appended to the separator value.

Example 3. Assign separator to the document title

[separator=::]
= Main Title:: Subtitle

You can also assign a separator using a document attribute title-separator in the header.

Example 4. Assign title-separator to the document title

= Main Title:: Subtitle
:title-separator: ::

title-separator can also be assigned via the CLI.

$ asciidoctor -a title-separator=:: document.adoc

Partition the title using the API

You can partition the title from the API when calling the doctitle method on Document:

Example 5. Retrieving a partitioned document title

title_parts = document.doctitle partition: true
puts title_parts.title
puts title_parts.subtitle

You can partition the title in an arbitrary way by passing the separator as a value to the partition option. In this case, the partition option both activates subtitle partitioning and passes in a custom separator.

Example 6. Retrieving a partitioned document title with a custom separator

title_parts = document.doctitle partition: '::'
puts title_parts.title
puts title_parts.subtitle