riscv · Bill Traynor (wmat) · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -0,0 +1,38 @@
+# Changes
+
+## 2026-06-08 — Antora structure and documentation site guidance
+
+### New files
+
+- `src/antora-structure.adoc` — New section documenting the Antora-based repository layout used by RISC-V specification repositories. Covers `antora.yml`, `modules/ROOT/pages/`, `modules/ROOT/nav.adoc`, `modules/ROOT/images/`, and how to register a specification with the RISC-V documentation site by submitting a pull request to [riscv-admin/antora-dev.riscv.org](https://github.com/riscv-admin/antora-dev.riscv.org). Includes content-source entry format, chapter numbering rules configuration, branch naming conventions, and Antora installation instructions.
+
+### Modified files
+
+**`src/docs-dev-guide.adoc`**
+- Added `include::antora-structure.adoc[]` between `authoring.adoc` and `a_few_basics.adoc`.
+
+**`src/authoring.adoc`**
+- Updated repository reference from `docs-templates` to `docs-spec-template`.
+- Replaced stale `asciidoctor book_header.adoc` quick-build command with the correct entry point (`asciidoctor modules/ROOT/pages/spec-sample.adoc`) and a `make` alternative.
+- Updated description of template repo to reflect Antora-based directory structure.
+
+**`src/a_few_basics.adoc`**
+- Updated two references to `book_header.adoc` (lines 91 and 334) to `modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo.
+
+**`src/build-infrastructure.adoc`**
+- Added `=== Source directory` subsection noting that `SRC_DIR` is now `modules/ROOT/pages/` and cross-referencing the antora-structure section.
+- Added `[[spec-types]]` subsection distinguishing ISA specifications (authored on a branch/fork of riscv-isa-manual) from non-ISA specifications (authored in an autonomous repository using docs-spec-template).
+- Added `[[spec-lifecycle]]` section defining the four specification states (Draft, Stable, Frozen, Ratified) with `:revremark:` examples and a link to `riscv.org/spec-state`.
+- Documented that state advancement is entirely manual — no automation promotes a specification between states.
+- Documented the non-ISA release process using the `workflow_dispatch` GitHub Actions trigger, including the `revision_mark` input and a note on keeping it consistent with `:revremark:` in the source.
+- Documented that ISA specification state is managed within the relevant chapter(s) of the riscv-isa-manual branch where the author is working.
+
+**`src/intro.adoc`**
+- Added `[[getting-help]]` subsection consolidating help resources: `sig-documentation` mailing list, `help@riscv.org`, docs-dev-guide GitHub issues, and antora-dev.riscv.org GitHub issues.
+
+**`local_build.md`**
+- Updated `## AsciiDoc book headers and styles` section to reference `modules/ROOT/pages/spec-sample.adoc` as the document entry point and `docs-resources/global-config.adoc` for shared attributes.
+- Updated `## Create and name a new .adoc file` to reflect the Antora workflow: new files go in `modules/ROOT/pages/`, are included in `spec-sample.adoc` for the PDF build, and registered in `modules/ROOT/nav.adoc` for the Antora site.
+- Updated `## HTML build` section to use `make` and the correct entry point (`modules/ROOT/pages/spec-sample.adoc`) in place of stale `book_header.adoc` references.
+- Added `## Antora site build` section covering `make antora`, output location, and Antora installation (`npm install -g antora`).
+- Added `## Run a local Kroki server for diagrams` section with the Docker run command (`docker run -d -p 9870:8000 yuzutech/kroki`), a stop command, and a note that the dev playbook is already configured for `localhost:9870`.
diff --git a/local_build.md b/local_build.md
@@ -218,6 +218,26 @@ wavedrom-cli
 
 WARNING: For the MacOS, if you upgrade from a prior version to Big Sur, you must reinstall first the NPM and then the NPM version of the wavedrom-cli.
 
+## Run a local Kroki server for diagrams
+
+The RISC-V documentation site uses [Kroki](https://kroki.io) to render diagrams (including WaveDrom, Bytefield, Graphviz, and others) server-side. The dev playbook at `antora-dev.riscv.org` is configured to reach a local Kroki instance on port 9870.
+
+Start the Kroki server with Docker:
+
+```cmd
+docker run -d -p 9870:8000 yuzutech/kroki
+```
+
+The `-d` flag runs it in the background. The container will restart automatically on subsequent Docker starts unless explicitly stopped.
+
+To stop it:
+
+```cmd
+docker stop $(docker ps -q --filter ancestor=yuzutech/kroki)
+```
+
+The dev playbook already has `kroki-server-url: http://localhost:9870` set in its `asciidoc.attributes`, so no additional configuration is needed once the container is running.
+
 ## Graphviz is used for diagrams in some appendices
 
 To support graphviz on the Mac, use brew
@@ -264,47 +284,75 @@ You can then add a bibliography to your appendices and use bibtex conventions to
 Details of how to work with bibtex and the RISC-V bibliogrpahy are in the example.pdf file.
 
 
-## AsciiDoc book headers and styles
+## AsciiDoc document header and styles
 
-Attributes in the book headers for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `risc-v_spec-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon.
+Attributes in the document header for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `docs-resources/themes/riscv-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon.
 
-In addition, properties in the book header within this repo point to the `images` directory and also the `resources/riscv-spec.bib` file that contains the RISC-V `bibtex` entries for use in creating a bibliography as one of the appendices.
+The entry point for the build is `modules/ROOT/pages/spec-sample.adoc`. This file contains the document header attributes and uses `include::` directives to pull in the chapter files. The `docs-resources/global-config.adoc` submodule file provides shared attributes such as `:company:` and `:doctype:`.
 
-For shorter documents, you have the option of using a report header, however, we have not yet provided branding for it.
+NOTE: The header is already in the template. The only changes you normally need to make are to update `:revnumber:`, `:revremark:`, and author metadata, then add chapter files using `include::chapter.adoc[]` in the order you want them to appear.
 
-NOTE: The headers are already in the template files. The only changes you normally need to make are to add chapter-sized sections in using the syntax `include::filename.adoc[]` in the order by which you want them to appear.
+## Create and add a new chapter file
 
-## Create and name a new .adoc file
-
-- In your text editor, create a new file.
-- Assign a name and save with the .adoc extension.
-- In the first line, add `[file_name]` (using a meaningful string for the filename) and in the second line, use a double "==" to indicate a topic heading, add some content, and save the file with an `.adoc` file extension.
-- In the header file, add `include::file_name.adoc` and save it.
-
-NOTE: Blank lines are not allowed in between the `include::file_name.adoc` files.
+- In your text editor, create a new file in `modules/ROOT/pages/`.
+- Assign a meaningful name and save it with the `.adoc` extension.
+- Begin the file with a section heading (`==`) rather than a document title (`=`), since it will be included into `spec-sample.adoc`.
+- Add an `include::chapter-name.adoc[]` line in `modules/ROOT/pages/spec-sample.adoc` in the position where you want the chapter to appear.
+- Add an `xref:chapter-name.adoc[Chapter Title]` entry to `modules/ROOT/nav.adoc` so the chapter appears in the Antora site navigation.
 
 ## HTML build
 
 Building in HTML is a good way to check that your content under development builds properly.
 
-As soon as you have installed Asciidoctor, you can build HTML content from any `.adoc` file on your own machine--simply CD into the directory that contains your `.adoc` files and run the following:
+The simplest approach from the repository root is:
+
+```cmd
+make
+```
+
+This builds both PDF and HTML output to the `build/` directory, using Docker if available or native tooling otherwise.
+
+To build HTML only without the Makefile, run:
+
+```cmd
+asciidoctor modules/ROOT/pages/spec-sample.adoc
+```
+
+For pdf output without the Makefile, cd into the repository root and use:
+
+```cmd
+asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg \
+  -r asciidoctor-bibtex -r asciidoctor-diagram \
+  -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+  -a pdf-fontsdir=docs-resources/fonts/ \
+  modules/ROOT/pages/spec-sample.adoc
+```
+
+ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the `=` get replaced with a `#`, causing an error message about fonts.
+
+## Antora site build
+
+To preview how the specification will appear as a multi-page HTML site (as it will be published on the RISC-V documentation site), use:
 
 ```cmd
-asciidoctor any_file_name.adoc
+make antora
 ```
-This generates a file named `any_file_name.html`.
 
-For pdf output, cd into this cloned directory and use this command:
+Output is written to `build/site/`. This requires Node.js 18+ and either `antora` on your PATH or `npx` available.
+
+### Install Antora
 
 ```cmd
-asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg -r asciidoctor-bibtex -r asciidoctor-diagram book_header.adoc -a pdf-style=resources/themes/riscv-pdf.yml -a pdf-fontsdir=resources/fonts/
+npm install -g antora
 ```
 
-This generates a file named `book_header.pdf` that makes use of the graphics, styles, and fonts that is identical to example.pdf.
+Verify:
 
-ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the '=' get replaced with a '#', causing an error message about fonts.
+```cmd
+antora --version
+```
 
-For your own content, change the name of the header file to a meaningful file name, and change the `include::filename.adoc` as needed.
+If you prefer not to install globally, `make antora` will automatically fall back to `npx antora` if `antora` is not on your PATH.
 
 ## AsciiDoc  and Asciidoctor toolchain documentation
 

diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc
@@ -88,7 +88,7 @@
 Index
 ```
 
-NOTE: Settings in the header file (`book_header.adoc` in the docs-templates repo) trigger auto-generation of Appendix prefixes and of the Index (among other things).
+NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo) trigger auto-generation of Appendix prefixes and of the Index (among other things).
 
 === Lists
 
@@ -331,7 +331,7 @@
 
 ==== Table captions
 
-The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style.
+The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style.
 
 To set a caption for a table or image, use the pattern as follows:
 

diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc
@@ -0,0 +1,162 @@
+[[antora-structure]]
+== Antora repository structure
+
+RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables individual specification repositories to be assembled into the RISC-V documentation site by Antora while also supporting a standalone PDF and HTML build via `make`.
+
+=== Repository layout
+
+A specification repository contains 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> Git submodule providing shared fonts, themes, and images.
+<4> Navigation file — defines the sidebar structure for the Antora site.
+<5> Symlink to `docs-resources/images` so Antora can find shared images.
+<6> All AsciiDoc source files live here.
+<7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute.
+<8> 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 https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It 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) used when the documentation site is assembled.
+
+[source,yaml]
+----
+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.
+<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`) once the specification is released.
+<4> Path to the navigation file, relative to `antora.yml`.
+
+When creating a new specification repository from the template, at minimum rename `name` and `title` to match your 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:
+
+. Create the `.adoc` file in `modules/ROOT/pages/`.
+. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build).
+. 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. It uses a nested list of `xref:` macros.
+
+[source,adoc]
+----
+* xref:spec-sample.adoc[RISC-V Example Specification]
+** xref:intro.adoc[Introduction]
+** xref:chapter2.adoc[The Second Chapter]
+** xref:contributors.adoc[Contributors]
+** xref:bibliography.adoc[Bibliography]
+----
+
+Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the sidebar order.
+
+=== modules/ROOT/images/
+
+This directory is a symlink to `docs-resources/images`, which contains the shared RISC-V logo and other common images. Antora requires images to be located within the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly.
+
+Place any specification-specific images in this directory alongside the symlinked shared images, or manage them via the symlink target in `docs-resources/`.
+
+[[dev-playbook]]
+=== Publishing to the RISC-V documentation site
+
+The RISC-V documentation site is assembled from all specification repositories by a central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. 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, Antora-ready branches are named with the version and an `-antora` suffix:
+
+----
+v1.0-antora
+v20250312-antora
+----
+
+Create this branch from your specification's release tag or working branch once 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:
+
+[source,yaml]
+----
+# 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 contains symlinks.
+
+==== Adding numbering rules
+
+The playbook uses custom extensions to number chapters and appendices 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 via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block:
+
+[source,yaml]
+----
+# --- 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`) that are numbered 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–4.
+<5> Omit this line entirely if your specification has no appendices.
+
+==== Submitting the pull request
+
+. Fork or branch https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org].
+. Add your content source and numbering rules to `antora/antora-playbook.yml` as described above.
+. Open a pull request against the `main` branch with a brief description of the specification being added.
+
+[[install-antora]]
+=== Installing Antora
+
+Antora is needed to run a local site preview. It requires Node.js version 18 or later. Once Node.js is installed, install Antora globally:
+
+[source,cmd]
+----
+npm install -g antora
+----
+
+Verify the installation:
+
+[source,cmd]
+----
+antora --version
+----
+
+For Node.js installation instructions, see https://nodejs.org/en/download/[nodejs.org].