On this page, you’ll learn:
How to structure a valid AsciiDoc page header.
How to set a page title.
How to add metadata to a page.
How to set AsciiDoc’s built-in page attributes.
The page header is a set of contiguous lines that start on the first line of the file. The header is separated from the page body by at least one blank line.
= Page Title (1) First Middle Last <firstname.lastname@example.org> (2) :description: A description of the page stored in an HTML meta tag. (3) :keywords: comma-separated values, stored, in an HTML, meta, tag (4) :sectanchors: (5) :url-repo: https://my-git-repo.com (6)
|1||Title of the page|
|2||Author name and email address|
|5||Example of a built-in page attribute|
|6||Example of a user created and defined page attribute|
Each attribute entry must be entered on its own line. Attributes can be placed in any order in the header, including above the page title. However, the preferred placement is below the title. The header can also contain comments.
A page title is specified by one equals sign (
=), followed by one blank space, and then the text of the title.
= The title of this page
AsciiDoc provides several optional, built-in attributes for defining page metadata.
Specifying the author or authors of a page is optional.
The author is listed on the line directly beneath the page’s title.
An optional email address or contact URL can follow an author’s name inside a set of angle brackets (
When a page has multiple authors, each author is separated by a semicolon (
= Page Title First Middle Last <email@example.com>; First Last <firstname.lastname@example.org>
Author names are output to the HTML
<head> <meta charset="UTF-8"> <meta name="author" content="First Middle Last, First Last">
Whether any author information is also displayed on a published page depends on the site’s UI templates.
Refer to the Asciidoctor user manual for additional author attributes and methods for specifying author information.
description is output to an HTML
<meta> tag with the same name.
You can break long values across several lines by ending each line with a backslash
\ that is preceded by a space.
= Page Title :description: A description of the page stored in an HTML meta tag. This page is \ about all kinds of interesting things.
<head> <meta charset="UTF-8"> <meta name="description" content="A description of the page stored in an HTML meta tag. This page is about all kinds of interesting things.">
The keywords attribute contains a list of comma-separated values that are assigned to an HTML
<meta> tag with the same name.
= Page Title :keywords: comma-separated values, stored, in an HTML, meta, tag
<head> <meta charset="UTF-8"> <meta name="keywords" content="comma-separated values, stored, in an HTML, meta, tag">
AsciiDoc provides numerous built-in attributes that can activate and control syntax output behavior and styles.
|If you’re not familiar with AsciiDoc attribute restrictions or operations precedence, review the attributes section of the Asciidoctor manual.|
Page attributes are set in the header and are available to the whole page. Built-in AsciiDoc attributes are reserved attributes that have special, pre-defined behavior. Many built-in attributes also have a restricted set of accepted values.
Built-in page attributes usually do two things; they toggle a behavior on or off (boolean), and they change the generated output by accepting an alternate value or replacement content (variable).
Let’s turn on the attribute
= Page Title :sectanchors:
When turned on,
sectanchors adds an anchor to the left of each section title.
The anchor is rendered as the symbol
The attribute is turned on, also known as set, by simply entering it into the header.
Built-in attributes that are on by default, like
table-captions, can be unset (turned off) with a leading or trailing
! added to its name.
= Page Title :sectanchors: :table-caption!:
Let’s look at an example of a built-in attribute that has a default value that we want to replace with a custom value.
The label on a Note admonition is controlled by the attribute
This attribute is set (on) by default and has an implicit value of
Let’s change the value to “OPS HINT”.
= Page Title :note-caption: OPS HINT
Now, when we create a Note admonition, its label is displayed as OPS HINT.
|This is an Ops Hint.|