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 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 file:

  • is saved in a pages directory

  • is saved using a URL-compliant filename and the .adoc file extension

  • has a title

  • is marked up with valid AsciiDoc syntax