Document Header

The document header is a special set of contiguous lines at the start of the document that encapsulates the document title, author and revision information, and document-wide attributes (either built-in or user-defined).

The header typically begins with a document title, though this element is optional. If a document title is specified, it may be immediately followed by two optional lines of text to set the author and revision information. Finally, the header may declare document-wide attributes (built-in or user-defined) using attribute entries. Attribute entries can be placed anywhere in the header, including above the document title, though the preferred placement is below the document title, if present. Since the document title is optional, it’s possible for the header to only consist of attribute entries.

The first block content (e.g., a paragraph) or a blank line in the document marks the end of the header. Any attributes defined below the document header will not be scoped to the document.

The document header must not contain any blank lines or block content!

Line comments may be used in the header, but only if those lines are directly adjacent to other lines in the header.

The header is optional when the doctype is article or book. However, a header is required when the document type is manpage. The requirements for a manual page (man page) are described in the asciidoctor:manpage:index.adoc.

The header (document title, author, and revision information) is included by default when converting to a standalone document. This means that the header of a document called via an include directive will be processed and converted. If you do not want the header of a document to be displayed, set the noheader attribute in the document’s header, CLI, or API.

Front matter

Many static site generators, such as Jekyll and Middleman, rely on front matter added to the top of the document to determine how to convert the content. Asciidoctor has a number of attributes available to correctly handle front matter. See the asciidoctor:publish:static-site-generators.adoc to learn how Asciidoctor integrates with static website generators.

Now let’s explore the document title in detail.