How to Set Up Antora Compliance

Configure an Antora documentation site that passes all WRAAS compliance checks on first evaluation.

Goal: Configure an Antora documentation site that passes all WRAAS compliance checks on first evaluation. A failed first evaluation generates a follow-up item. The follow-up item does not expire. It will be raised next sprint.

Prerequisites

Antora installed and operational
AsciiDoc content (not Markdown — see the Why Not Markdown explanation)
A willingness to add :description: attributes to every page, including the ones you wrote last year and considered done

Required Site Structure

Directory tree

docs/
  antora.yml
  modules/
    ROOT/
      nav.adoc
      pages/
        index.adoc
        ...

Steps

Configure antora.yml with the required attributes to enable description enforcement:

YAML — antora.yml

name: your-component
version: '1.0'
title: Your Component Title
asciidoc:
  attributes:
    page-description: true    # enables description attribute enforcement

Add required page attributes to every .adoc file. WRAAS checks every file. This includes the ones in the subdirectory you have not opened since initial commit.

AsciiDoc — every .adoc page
```
= Page Title
:description: A clear, one-sentence description of this page.
:keywords: relevant, terms

Content begins here.
```
Ensure nav.adoc lists every page in the module. An unlisted page is a compliance violation. WRAAS considers it philosophically troubling and raises a question before it raises anything else.
Run wraas status to confirm the Antora compliance engine has registered the new structure. Output should include Antora compliance: ACTIVE. If it does not, the configuration file has not been applied yet.

💡

Tip

The :description: attribute is not optional from WRAAS's perspective. It is optional from Antora's perspective. These are different perspectives. WRAAS's perspective is the one that generates the follow-up comment.

⚡

Caution

nav.adoc must list every page in the module. An unlisted page is an orphaned page. An orphaned page is a page that exists but cannot be found. WRAAS considers this philosophically troubling and will raise a question(non-blocking): is this page intentionally unreachable? comment.