Antora page schema

Built-in id: antora:page:3.1

Published at https://hawkeyexl.github.io/manni/schemas/antora/3.1.json. A $schema that names this URL resolves to the bundled copy, with no network call.

antora:page:3.1 checks the AsciiDoc document header of an Antora 3.1 page. It requires title, because the page title is the only mandatory header element in Antora. It is one of the platform schemas, which say what a generator accepts rather than what your team agreed.

Antora page metadata lives in the AsciiDoc document header, not in front matter. The reader takes the = Title line plus every :name: value attribute entry above the first blank line.

Property	Value
Id	`antora:page:3.1`
Title	Antora page header attributes v3.1
Files it fits	`.adoc`, `.asciidoc`
Dialect	Draft 2020-12
Required fields	`title`
Additional properties	Allowed (`additionalProperties: true`)
Reference kind	builtin
On by default	No
Upstream reference	Page attributes
JSON	`antora/3.1.json`

Use it

Antora content lives in per-component modules/*/pages trees, so the override is usually a glob rather than a single root:

meta:
  overrides:
    - files: "**/modules/*/pages/**"
      schemas:
        - antora:page:3.1

For a one-off run, pass the id directly:

manni meta validate modules/ROOT/pages/ -s antora:page:3.1

Fields

Attribute	Type	Notes
`title`	string	Required. The `= Title` line.
`description`	string	AsciiDoc built-in; becomes an HTML meta tag.
`keywords`	string	AsciiDoc built-in. A comma-separated string, never a list.
`navtitle`	string	Link text used by the navigation.
`page-aliases`	string	Comma-separated alternate resource IDs.
`page-layout`	string	Which UI template renders the page.
`page-partial`	boolean	`:page-partial:` is true, `:!page-partial:` is false.
`page-role`	string	Body classes. The default UI reserves `-toc`.
`page-toclevels`	integer	0–5.
`page-tags`	string	Comma-separated, same typing as `keywords`.

Two things about AsciiDoc typing catch people out, and the schema is built around both:

Attribute values are text. :keywords: setup, reference reaches the validator as the single string "setup, reference". Typing it as an array would fail every real Antora page, so it is a string.
A bare attribute is true. :page-partial: with no value is the boolean true, and the unset form :!page-partial: is false. Numbers are typed too, so :page-toclevels: 3 is the number 3 and not "3".

Additional properties

Antora defines only three predefined page attributes: page-aliases, page-layout and page-partial. The rest of the page-* namespace is yours, and custom attributes pass unchecked.

Example page

A header carrying every described attribute. This is test/fixtures/platform/antora-valid.adoc, and it passes.

= Configure the Playbook
:description: How to point a playbook at your content sources.
:keywords: playbook, antora, configuration
:navtitle: Playbook
:page-aliases: playbook-setup.adoc, old-playbook.adoc
:page-layout: default
:page-role: -toc
:page-toclevels: 3
:page-tags: setup, reference
:!page-partial:

The playbook tells Antora where the content lives.

A common mistake

Attribute entries with no = Title line above them make a page Antora will not build:

:description: An attribute entry with no page title above it.
:page-layout: default

Body.

✗ test/fixtures/platform/antora-missing-title.adoc
    (root)  must have required property 'title'  (line 1)  [antora:page:3.1]

1 file checked, 0 passed, 1 failed, 1 error

Add the = Title line as the first line of the header.