Document Header

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.

Document header structure

The document header is a series of contiguous lines that starts on the first line of the file.

The document header can’t contain blank lines or block content. The first blank 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.

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 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.

When does the document header end?

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.

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 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.

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 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.

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.