Document Header

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

Document header structure

The optional document header is a series of contiguous lines at the start of the AsciiDoc source, after skipping any empty or comment lines. If a document has a header, no content blocks are permitted above it. In other words, the document must start with a document header if it has one.

The document header may not contain empty lines. The first empty line the processor encounters after the document header begins marks the end of the document header and the start of the document body.

A header typically begins with a Document Title. When a document title is specified, it may be immediately followed by one or two designated lines of content. These implicit content lines are used to assign Author Information and Revision Information to the document.

The header may contain the following elements as long as there aren’t any empty lines between them:

  • optional document title (a level-0 heading)

  • optional author line or author and revision lines if the document title is present (should immediately follow the document title)

  • optional document-wide attributes (built-in and user-defined) declared using attribute entries,

    • includes optional metadata, such as a description or keywords

  • optional comment lines

Notice in Example 1 that there are no empty lines between any of the entries. In other words, the lines are contiguous.

Example 1. Common elements in a header
// this comment line is ignored
= Document Title (1)
Kismet R. Lee <> (2)
:description: The document's description. (3)
:sectanchors: (4)
:url-repo: (5)
The document body starts here.
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 The document body is separated from the document header by an empty line

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

If you put content blocks above the document header when using the default article doctype, you will see the following warning:

level 0 sections can only be used when doctype is book

While this warning can be mitigated by changing the doctype to book, it may lead to a secondary warning about an invalid part. That’s because the document title will be repurposed as a part title and any lines that follow it as content blocks. If you’re going to use the book doctype, you must structure your document to use Book Parts.

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.