Document Header

An AsciiDoc document may begin with a document header. The document header encapsulates the document title, author and revision information, document metadata, and document-scoped attributes.

Document header structure

If present, the document header is a sequence of contiguous lines that start at the top of the file, ignoring any empty lines or comments.

The document header cannot contain empty lines. The first empty line that the processor encounters after the document header begins marks 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 empty lines between any of the entries:

Notice in Example 1 that there are no empty lines between any of the entries; the lines are contiguous.

Example 1. Common elements in a header
= Document Title (1)
Kismet R. Lee <kismet@asciidoctor.org> (2)
:description: The document's description. (3)
:sectanchors: (4)
:url-repo: https://my-git-repo.com (5)
(6)
1 Document title
2 Author line
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 An empty 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.

When does the document header end?

The first empty line in the document marks the end of the header. The next line after the first empty line that contains content is interpreted as the beginning of the document’s body.

Example 2. Terminating a document header
= Document Title
Kismet R. Lee <kismet@asciidoctor.org>
:url-repo: https://my-git-repo.com
(1)
This is the first line of content in the document body. (2)
1 An empty line ends the document header.
2 After the empty 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 empty line are not part of the document header and will not be scoped to the entire document.

Header requirements per doctype

The header is optional when the doctype is article or book. A header is required when the document type is manpage. See the manpage doctype section for manual page (man page) requirements.

Header processing

The information in the document header is displayed by default when converting to a standalone document. 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.

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 Skip Front Matter to learn more.