////
Included in:

- user-manual: Header
////
//The document title is written as a level-0 section, which consists of a single equal sign followed by at least one space (i.e., `={sp}`) and the text of the title.
The document title resembles a level-0 section title, which is written using a single equal sign followed by at least one space (i.e., `={sp}`), then the text of the title.
The document title must be the first level-0 section title in the document.
The only content permitted above the document title are blank lines, comment lines and document-wide attribute entries.

Here's an example of a document title followed by a short paragraph.
Notice the blank line between the document title and the first line of prose.
That blank line is what offsets the document header from the body.

.Document with a title
[source]
----
include::ex-header-title.adoc[tag=base]
----

.Result: Rendered document title
====
image::sect0-title.png[Title of document]
====

When the `doctype` is `article` or `manpage`, the document can only have one level-0 section title.
In contrast, the `book` document type permits multiple level-0 section titles.
When the `doctype` is `book`, the first level-0 section title, located in the header, is the document's title and subsequent level-0 section titles are the part titles.

==== doctitle attribute

A document's title is assigned to the built-in `doctitle` attribute.
//Its value is identical to the value returned by `Document#doctitle`.
The doctitle attribute can be referenced anywhere in a document and resolves to the document's title when displayed.

.Referencing the doctitle attribute
[source]
----
include::ex-header-title.adoc[tag=doc]
----

.Result: doctitle output
====
image::doctitle.png[Doctitle attribute]
====

The `doctitle` attribute can also be used to set the document title instead of using a level-0 section title.
However, the attribute must still be set in the document header.

==== Document subtitle

Asciidoctor recognizes a subtitle in the primary level-0 heading.
If the primary title contains at least one colon followed by a space (i.e, `:{sp}`), Asciidoctor treats the text after the final colon-space sequence as the subtitle.

NOTE: The subtitle is not distinguished from the main title in the `html5` output.
It's only distinguished from the main title when using the `docbook`, `epub3`, and `pdf` converters.

.Document with a subtitle
[source]
----
include::ex-header-title.adoc[tag=sub-1]
----

In this example, the following is true:

[horizontal]
Main title:: The Dangerous and Thrilling Documentation Chronicles
Subtitle:: A Tale of Caffeine and Words

.Document with a subtitle and multiple colons
[source]
----
include::ex-header-title.adoc[tag=sub-2]
----

In this example, the following is true:

[horizontal]
Main title:: A Cautionary Tale: The Dangerous and Thrilling Documentation Chronicles
Subtitle:: A Tale of Caffeine and Words

Instead of using a colon followed by a space as the separator characters between the main title and the subtitle, you can specify a custom separator using the `title-separator` attribute.

.Document with a subtitle using a custom separator
[source]
----
include::ex-header-title.adoc[tag=sub-3]
----

Note that a space is always appended to the value of the `title-separator` (making the default value of the `title-separator` effectively a single colon).

Asciidoctor also provides an API for extracting the title and subtitle.
See the API docs for the https://www.rubydoc.info/gems/asciidoctor/Asciidoctor/Document/Title[Document::Title] for more information.
Support for subtitle functionality for other sections is being considered.
Refer to https://github.com/asciidoctor/asciidoctor/issues/1493[issue #1493].

==== Document title visibility

You can control whether or not the document title appears in the converted document using the `showtitle` attribute.

When converting a standalone document, the document title is shown by default.
If you don't want the title to be shown in this case, unset the `showtitle` attribute using `showtitle!` in the document header or via the CLI or API.

When converted to an embeddable document, the document title is _not_ shown by default.
If you want the title to be shown, set the `showtitle` attribute in the document header or via the CLI or API.
The author and revision information is not shown below the document title in the embeddable version of the document like it is in the standalone document, even when the `showtitle` attribute is set.

Let's look at how to add additional metadata to the document header, including an author and her email address.