You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

39 lines
2.3 KiB

4 years ago
////
Included in:
- user-manual
////
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.
[.lead]
*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 <<user-manual#man-pages,man pages>> section.
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 <<user-manual#include-directive,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 (or set the attribute using the API or 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 the <<user-manual#static-website-generators,static website generators>> section to learn how Asciidoctor integrates with static website generators.
****
Now let's explore the document title in detail.