Antora repository structure

RISC-V specification repositories use an Antora-compatible directory structure. This enables Antora to assemble individual specification repositories into the RISC-V documentation site while also supporting a standalone PDF and HTML build using make.

Repository layout

A specification repository has the following top-level files and directories:

antora.yml                    (1)
Makefile                      (2)
docs-resources/               (3)
modules/
  ROOT/
    nav.adoc                  (4)
    images/                   (5)
    pages/                    (6)
      spec-sample.adoc
      intro.adoc
      chapter2.adoc
      example.bib             (7)
      ...
    partials/                 (8)
1 Antora component descriptor: identifies this repo as an Antora component and provides component metadata and configuration.
2 Makefile: drives the PDF/HTML build.
3 docs-resources: Git submodule providing shared fonts, themes, and images.
4 nav.adoc file: the navigation file that defines the sidebar structure for the Antora site.
5 Images: Symlink to docs-resources/images so Antora can find shared images.
6 Pages directory: all AsciiDoc source files live here.
7 Resources directory: resource files that are not asciidoc or images such as the bibliography file. Referenced by spec-sample.adoc via the :bibtex-file: attribute.
8 Partials directory: Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with include::partial$filename.adoc[].

antora.yml

The antora.yml file at the repository root is the Antora component descriptor and serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) that Antora uses to assemble the documentation site.

name: spec-sample            (1)
title: RISC-V Example Specification (Zexmpl)  (2)
version: ~                   (3)
nav:
  - modules/ROOT/nav.adoc   (4)
1 Component name: used in Antora cross-references from other components (xref:spec-sample:page.adoc[]). Rename to match your specification. This attribute is used in the URL.
2 Human-readable title shown in the site UI. Update this for your specification.
3 ~ means unversioned. Set to a version string (e.g., 1.0) when you release the specification. During development, use standard two digit versioning such as 0.1, 0.2, etc.
4 nav: Path to the navigation file, relative to antora.yml. Using the template for non-ISA specifications, this should always be the same path, i.e. modules/ROOT/nav.adoc.

When creating a new specification repository from the template, set the page-group attribute to "development" and update it to reflect specification state through the specification lifecycle. Update the name and title attributes to match your specification. For example, the Debug Specification uses:

name: debug title: Debug Specification

modules/ROOT/pages/

All AsciiDoc source files live in modules/ROOT/pages/. This is the Antora convention for the default (ROOT) module’s page content.

The entry point for the standalone PDF and HTML build is spec-sample.adoc, which uses AsciiDoc include:: directives to pull in the other chapter files. For the Antora site build, each file in pages/ becomes a separate HTML page.

When adding a new chapter:

  1. Create the .adoc file in modules/ROOT/pages/. Start it with a level-0 title, = Chapter title. Antora uses that line as the page title, so a page that starts with ==, or has no title, is listed as "Untitled" on the site.

  2. Add an include:: directive for it in spec-sample.adoc (for the PDF build), with a level offset: include::../modules/ROOT/pages/my-chapter.adoc[leveloffset=+1]. The offset turns the page’s level-0 title into a chapter in the PDF. Without it, the PDF gets a second document title.

  3. Add an xref: entry for it in modules/ROOT/nav.adoc (for the Antora site build).

modules/ROOT/nav.adoc

The nav.adoc file defines the navigation sidebar shown in the Antora site.

* xref:index.adoc[RISC-V Example Specification]
** xref:copyright.adoc[Copyright and license information]
** xref:contributors.adoc[Contributors]
** xref:intro.adoc[Introduction]
** xref:chapter2.adoc[The Second Chapter]
** xref:bibliography.adoc[Bibliography]

Add a new entry here each time you add a chapter to pages/. The order of entries controls the left navigation order in the HTML version in the RISC-V Specifications Library.

modules/ROOT/images/

Antora locates images in the module directory tree. Store images used in the specification in the images directory.

Publishing to the RISC-V documentation site

A central Antora playbook maintained at riscv-admin/antora-dev.riscv.org assembles the RISC-V documentation site from all specification repositories. Specification authors do not manage their own playbook. Instead, they submit a pull request to that repository to register their specification as a content source.

Naming your branch

By convention, name Antora-ready branches with the version and an -antora suffix:

v1.0-antora
v20250312-antora

Create this branch from your specification’s release tag or working branch after the Antora directory structure is in place.

Adding a content source

In the playbook at antora/antora-playbook.yml, add an entry to the content.sources list. Use an existing entry as a model and follow the comment convention used throughout the file:

# My Specification — component: my-spec | chapters 5–12
- url: https://github.com/riscv/my-spec.git
  branches: [v1.0-antora]
  start_page: ROOT::index.adoc
  start_path: /
  worktrees: true
  submodules: true

The component name in the comment must match the name field in your antora.yml. Set submodules: true if your repository uses git submodules (e.g., docs-resources). Set worktrees: true if your repository has symlinks.

Adding numbering rules

The playbook uses custom extensions to number chapters and appendixes in the site navigation. Add a corresponding entry for your specification to both the nav_numbering_extension and section_numbering_extension blocks. Both blocks share the same rules from a YAML anchor (&numbering_rules / *numbering_rules), so you only need to add a single entry in the 'nav_numbering_extension` block:

# --- My Specification --------------------------------------------------
- component: my-spec         (1)
  module: ROOT               (2)
  branches: ['v1.0-antora']  (3)
  chapters: {start: 5, end: 12}  (4)
  appendices: {start: 13, end: 14}  (5)
1 Must match the name in your antora.yml.
2 Use ROOT for single-module specifications (the standard case).
3 Must match the branch name(s) listed in your content.sources entry.
4 The range of nav entries (top-level * items in nav.adoc) to number as chapters. Count from the first entry in nav.adoc — entries before your first chapter (e.g., a preface or overview page) are typically at position 1 through 4.
5 Omit this line entirely if your specification has no appendixes.

Submitting the pull request

  1. Fork or branch riscv-admin/antora-dev.riscv.org.

  2. Add your content source and numbering rules to antora/antora-playbook.yml as described above.

  3. Open a pull request against the main branch with a brief description of the specification added.

Installing Antora

You need Antora to run a local site preview. It requires Node.js version 18 or later. Once you install Node.js, install Antora globally:

npm install -g antora

Verify the installation:

antora --version

For Node.js installation instructions, see nodejs.org.