The document header is a series of contiguous lines at the start of the document that encapsulates the document title, author and revision information, metadata, and document-wide attributes.
The document header is a series of contiguous lines that starts on the first non-empty line of the file.
|The document header cannot contain empty lines. The first empty line that the processor encounters is interpreted as the end of the document header and the beginning of the document body.|
A header typically begins with a Document Title. When a document title is specified, it can be immediately followed by two special (but optional) lines of content that assign Author Information and Revision Information.
Additionally, the header can contain the following elements as long as there aren’t any blank lines between any of the entries:
Notice in Example 1 that there are no blank lines between any of the entries; the lines are contiguous.
= Document Title (1) Kismet R. Lee <email@example.com> (2) :description: The document's description. (3) :sectanchors: (4) :url-repo: https://my-git-repo.com (5) (6)
|3||Attribute entry assigning metadata to a built-in document attribute|
|4||Attribute entry setting a built-in document attribute|
|5||Attribute entry assigning a value to a user-defined document attribute|
|6||Blank line that ends the document header|
There are a few attribute entries in Example 1. Each attribute entry, whether built-in or user-defined, must be entered on its own line. While attribute entries can be placed anywhere in the header, including above the document title, the preferred placement is below the title, if it’s present. Since the document title is optional, it’s possible for the header to only consist of attribute entries.
The first blank line in the document marks the end of the header. The next line after the first blank line that contains content is interpreted as the beginning of the document’s body.
= Document Title Kismet R. Lee <firstname.lastname@example.org> :url-repo: https://my-git-repo.com (1) This is the first line of content in the document body. (2)
|1||A blank line ends the document header.|
|2||After the blank line, the next line with content starts the body of the document.|
The first line of the document body can be any valid AsciiDoc content, such as a section heading, paragraph, table, include directive, image, etc. Any attributes defined below the first blank line are not part of the document header and will not be scoped to the entire document.
The header is optional when the
A header is required when the document type is
See the manpage doctype section for manual page (man page) requirements.
The information in the document header 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 don’t want the header of a document to be displayed, set the
noheader attribute in the document’s header or via the CLI.
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 Skip Front Matter to learn more.