Subtitle

An optional subtitle can be appended to a document title.

The HTML 5 converter does not currently split the subtitle out from the document title when generating HTML from AsciiDoc. The document title is only partitioned into a main and subtitle in the output of the DocBook, EPUB 3, and PDF converters. However, the subtitle is still available via the API, so you could add support for it by extending the HTML 5 converter.

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