Set Up a Standard Page

A standard page has two parts, a header and a body.

Page header

The page header is a set of contiguous lines that start on the first line of the file. The header encapsulates the following elements:

Common elements in a page header
= Page Title (1)
:description: A description of the page stored in an HTML meta tag. (2)
:sectanchors: (3)
:url-repo: https://my-git-repo.com (4)
:page-tags: name of a tag, name of a tag (5)
1 Required page title entered on the first line of the file
2 Optional built-in description metadata attribute
3 Optional built-in AsciiDoc attribute
4 Optional custom AsciiDoc attribute
5 Optional custom Antora page- attribute

The page title must be defined using an Atx-style (single line) document title that begins with a single equals sign. Antora does not recognize the legacy Setext-style (two line) document title syntax once supported by AsciiDoc. If you use the Setext-style syntax, xrefs in the page will not be resolved and other features of AsciiDoc will not be available.

The attribute entries, whether built-in or custom, must each be entered on its own line. The header can also contain comment lines.

The page header ends by entering one or more blank lines.

Page body

The page header is separated from the page body by at least one blank line. The next line that contains content initiates the body of the page.

= Page Title
:description: A description of the page stored in an HTML meta tag.
:sectanchors:
:url-repo: https://my-git-repo.com
:page-tags: name of a tag, name of a tag
(1)
This is the first line of the page body. (2)

== Section heading

This is a paragraph in a section.
1 A blank line ends the page header.
2 After the blank line, the next line with content starts the body or the page.

The first line of the page body can be any valid AsciiDoc content, such as a section heading, paragraph, table, include directive, image, etc.

Page filename

A page is stored in a pages family directory. The page’s filename is used to compute its URL. If the filename begins with a dot (.) or ends without a file extension, Antora will ignore it. If the filename starts with an underscore (_), it will be added to the content catalog, but Antora won’t publish it.

Create a new standard page

  1. Open a new file in your preferred IDE or plain text editor.

  2. On the first line of the file, enter a page title. A page title is specified by one equals sign (=), followed by one blank space, and then the text of the title.

    = The Title of My New Page

  3. The page title is the only required header element. Separate the header block from the body block by one blank line. Write your content.

    = The Title of My New Page

Welcome to my new page!

  4. Save the file with the extension .adoc in a pages directory. The name you use when saving the file will be used to compute the page’s URL.

You’ve created a standard page! When you run Antora, it will be converted to an HTML page and published to your site automatically.

The page created in this example is simple. Using AsciiDoc, a page’s header can encompass a wide range of capabilities and its body can handle complex content.

Key Points to Remember

A page:

  • is stored in the pages directory of a module

  • has the .adoc file extension

  • has a filename that only contains URL-compliant characters

  • has a filename that’s all lowercase (optional, but recommended)

  • has a filename that does not contain spaces (optional, but recommended)

  • has a title (i.e., document title)

  • is marked up using valid AsciiDoc syntax

Using spaces in the filename is not recommended. Spaces have to be encoded in a URL and this can lead to URLs which look unfamiliar to visitors. It’s best to avoid spaces (and only use lowercase letters) when choosing a filename for a page.