101 add antora file structure requirements

.gitignore

@@ -1,2 +1,4 @@
 /build/*
 /images/*
+node_modules/
+.cache/

CHANGELOG.md

@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.0] - 2026-06-08
+
+### Added
+- `antora.yml` — Antora component descriptor at the repository root. Authors must update `name` and `title` to match their specification.
+- `modules/ROOT/nav.adoc` — Antora navigation file defining the sidebar structure for the documentation site.
+- `modules/ROOT/images` — Symlink to `docs-resources/images` so Antora can locate shared images within the module tree.
+- `modules/ROOT/pages/` — Antora-standard content directory. All AsciiDoc source files moved here from `src/`.
+- `antora-playbook.yml` — Local Antora playbook for previewing the specification as a multi-page HTML site via `make antora`.
+- `antora` Makefile target — Builds a local Antora site to `build/site/`. Uses system `antora` or falls back to `npx antora`.
+- `node_modules/` and `.cache/` added to `.gitignore` for Antora build artifacts.
+
+### Changed
+- Moved all AsciiDoc source files and `example.bib` from `src/` to `modules/ROOT/pages/`.
+- `Makefile` `SRC_DIR` updated from `src` to `modules/ROOT/pages`.
+- `modules/ROOT/pages/spec-sample.adoc` — Updated `docs-resources` relative paths to reflect new depth within the Antora module tree, and updated `bibtex-file` path accordingly.
+
 ## [4.0.0] - 2004-01-27
 - Workflow improvements
 - Makefile refactoring

Makefile

@@ -36,7 +36,7 @@ ifneq ($(SKIP_DOCKER),true)
 	DOCKER_QUOTE := "
 endif
 
-SRC_DIR := src
+SRC_DIR := modules/ROOT/pages
 BUILD_DIR := build
 
 DOCS_PDF := $(DOCS:%.adoc=%.pdf)
@@ -61,7 +61,7 @@ REQUIRES := --require=asciidoctor-bibtex \
 			--require=asciidoctor-lists \
             --require=asciidoctor-mathematical
 
-.PHONY: all build clean build-container build-no-container build-docs
+.PHONY: all build clean build-container build-no-container build-docs antora
 
 all: build
 
@@ -95,6 +95,18 @@ build-no-container:
 	$(MAKE) SKIP_DOCKER=true build-docs
 	@echo "Build completed successfully."
 
+antora:
+	@echo "Building Antora site..."
+	@if command -v antora >/dev/null 2>&1; then \
+		antora antora-playbook.yml; \
+	elif command -v npx >/dev/null 2>&1; then \
+		npx antora antora-playbook.yml; \
+	else \
+		echo "Antora not found. Install with: npm install -g antora"; \
+		exit 1; \
+	fi
+	@echo "Antora site built to build/site/"
+
 # Update docker image to latest
 docker-pull-latest:
 	${DOCKER_BIN} pull ${DOCKER_IMG}

antora-playbook.yml

@@ -0,0 +1,24 @@
+# Antora Playbook
+# https://docs.antora.org/antora/latest/playbook/
+#
+# Used by the `make antora` target to build the HTML site locally.
+# For CI/CD, a separate playbook in your docs site repository will
+# typically reference this component repository by URL.
+
+site:
+  title: RISC-V Specification
+  url: https://docs.riscv.org
+  start_page: spec-sample::spec-sample.adoc
+
+content:
+  sources:
+    - url: .
+      branches: HEAD
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip
+    snapshot: true
+
+output:
+  dir: ./build/site

antora.yml

@@ -0,0 +1,12 @@
+# Antora Component Descriptor
+# https://docs.antora.org/antora/latest/component-version-descriptor/
+#
+# This file defines the Antora component for this RISC-V specification.
+# Rename `name` and `title` to match your specification.
+
+name: spec-sample
+title: RISC-V Example Specification (Zexmpl)
+version: ~
+
+nav:
+  - modules/ROOT/nav.adoc

modules/ROOT/images

@@ -0,0 +1 @@
+../../docs-resources/images

modules/ROOT/nav.adoc

@@ -0,0 +1,10 @@
+// Navigation file for Antora
+// https://docs.antora.org/antora/latest/navigation/
+//
+// Update this file to reflect your specification's chapter structure.
+
+* 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]

modules/ROOT/pages/bibliography.adoc

@@ -0,0 +1,4 @@
+[bibliography]
+== Bibliography
+
+bibliography::[]

modules/ROOT/pages/chapter2.adoc

@@ -0,0 +1,48 @@
+[[chapter2]]
+== The Second Chapter
+
+. The first item.
+
+. The second item.
++
+.. The first sub item.
+
+.. The second sub item.
++
+[CAUTION]
+====
+A moment of caution is required for this block of text must be read and apreciated for its importance.
+====
+
+. Yet another item.
+
+. Again, an item.
+
+.. A multi-line item.
++
+This item has multiple lines.
++
+By multiple lines, this is what we mean.
++
+Seriously, multiple.
+
+=== An example table
+
+.Nonsensical table
+[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"]
+|===
+4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area
+|L|R|W|X|Quarter 1|Quarter 2
+|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors
+|0|0|0|1|Thing 1|Thing 2
+|1|0|0|0|Thing 3|Thing 4
+|1|1|1|1 2+|Span Thing 1 and 2
+|===
+
+=== Sub section
+
+Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet.
+
+=== Yet another subsection
+
+Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur.

modules/ROOT/pages/contributors.adoc

@@ -0,0 +1,7 @@
+== Contributors
+
+This RISC-V specification has been contributed to directly or indirectly by:
+
+[%hardbreaks]
+* Author1 <required1@email.com>
+* Author2 <required2@email.com>

modules/ROOT/pages/example.bib

@@ -0,0 +1,36 @@
+@inproceedings{riscI-isca1981,
+  title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer},
+  author = {David A. Patterson and Carlo H. S\'{e}quin},
+  booktitle = {ISCA},
+  location = {Minneapolis, Minnesota, USA},
+  pages = {443-458},
+  year = {1981}
+}
+
+@inproceedings{Katevenis:1983,
+  author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin},
+  title = {The {RISC II} micro-architecture},
+  booktitle = {Proceedings VLSI 83 Conference},
+  year = {1983},
+  month = {August}
+}
+
+@inproceedings{Ungar:1984,
+  author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson},
+  title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}},
+  booktitle = {ISCA},
+  address = {Ann Arbor, MI},
+  year = {1984},
+  pages = {188-197}
+}
+
+@article{spur-jsscc1989,
+  author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson},
+  title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing},
+  journal = {IEEE JSSC},
+  year = {1989},
+  volume = {24},
+  number = {6},
+  pages = {1688-1698},
+  month = {December}
+}

modules/ROOT/pages/index.adoc

@@ -0,0 +1,2 @@
+[index]
+== Index

modules/ROOT/pages/intro.adoc

@@ -0,0 +1,43 @@
+[[intro]]
+== Introduction
+
+Lorem ipsum indexterm:[Lorem ipsum] dolor sit amet, consectetur adipiscing elit, sed do *eiusmod tempor* incididunt ut labore et dolore magna aliqua. Felis imperdiet proin fermentum leo vel orci porta. Volutpat lacus laoreet non curabitur indexterm:[curabitur] gravida indexterm:[gravida]. Posuere urna nec tincidunt praesent semper feugiat nibh. Elit ``ullamcorper`` dignissim cras tincidunt lobortis. Malesuada fames ac turpis egestas integer eget. Tristique sollicitudin nibh sit amet commodo. Sed felis eget velit aliquet. Sit amet aliquam id diam maecenas ultricies mi. Consectetur purus ut faucibus pulvinar. Lectus urna duis convallis convallis tellus id. Fermentum iaculis eu non diam. Feugiat in fermentum posuere urna nec tincidunt praesent semper feugiat. Urna nec tincidunt praesent semper feugiat nibh.
+
+.Nonsensical code
+[source, python]
+----
+def banana_apple():
+    x = "banana"
+    y = "apple"
+    for i in range(len(x)):
+        print(x[i], y[i])
+        z = x + y
+    return z
+
+result = banana_apple()
+print("Result:", result)
+----
+
+Commodo viverra maecenas accumsan lacus. Vulputate odio ut enim blandit indexterm:[blandit] volutpat maecenas volutpat blandit. Urna porttitor rhoncus dolor purus non. Tellus mauris a diam maecenas sed. Vitae auctor eu augue ut lectus. Ridiculus mus mauris vitae ultricies leo integer. Consequat semper viverra nam *libero* justo laoreet sit amet. Pellentesque pulvinar pellentesque habitant morbi tristique senectus et netus et. Ac placerat vestibulum lectus mauris ``ultrices`` eros in cursus turpis. Accumsan in nisl nisi scelerisque eu ultrices vitae. Cras ornare arcu dui vivamus. Vitae congue mauris rhoncus aenean. Consequat mauris nunc congue nisi vitae suscipit tellus. Tempus egestas sed sed risus pretium quam vulputate dignissim. Quis varius quam quisque id diam vel. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Amet mauris commodo quis imperdiet massa tincidunt nunc.
+
+[NOTE]
+====
+The name RISC-V indexterm:[RISC-V] was chosen to represent the fifth major RISC ISA design from UC Berkeley (RISC-I cite:[riscI-isca1981], RISC-II cite:[Katevenis:1983], SOAR cite:[Ungar:1984], and SPUR cite:[spur-jsscc1989] were the first four). We also pun on the use of the Roman numeral "V" to signify "variations" and "vectors", as support for a range of architecture research, including various data-parallel accelerators, is an explicit goal of the ISA design.
+====
+
+=== Sub Section of Introduction
+
+Pellentesque habitant morbi *tristique* senectus et netus et. Aliquam purus sit amet luctus. Odio eu ``feugiat`` pretium nibh ipsum consequat nisl vel. Euismod lacinia at quis risus sed vulputate odio ut. Eu sem integer vitae justo eget. Cursus euismod quis viverra nibh. Tempus egestas sed sed risus. Quis imperdiet massa tincidunt nunc pulvinar. Id venenatis a condimentum vitae sapien pellentesque habitant.
+
+.Nonsensical wavedrom signals
+[wavedrom, svg]
+....
+{
+  "signal": [
+    { "name": "Clock", "wave": "P.......P" },
+    { "name": "Data", "wave": "x.x..xx.x" },
+    { "name": "Control", "wave": "0.1.01..0" },
+    { "name": "Error", "wave": "zZzZzZzZz" }
+  ]
+}
+....

modules/ROOT/pages/spec-sample.adoc

@@ -0,0 +1,78 @@
+= RISC-V Example Specification Document (Zexmpl)
+Authors: Author 1, Author 2
+include::../../../docs-resources/global-config.adoc[]
+:docgroup: RISC-V Task Group
+:description: RISC-V Example Specification Document (Zexmpl)
+:revdate: 1/2023
+:revnumber: 1.0
+:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details.
+:revinfo:
+:preface-title: Preamble
+:colophon:
+:appendix-caption: Appendix
+// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/
+:imagesdir: ../../../docs-resources/images
+:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center]
+// Settings:
+:experimental:
+:reproducible:
+//:WaveDromEditorApp: app/wavedrom-editor.app
+:imagesoutdir: images
+//:srcdir: src
+:bibtex-file: modules/ROOT/pages/example.bib
+:bibtex-order: alphabetical
+:bibtex-style: apa
+:icons: font
+:lang: en
+:listing-caption: Listing
+:sectnums:
+:toc: left
+:toclevels: 4
+:source-highlighter: pygments
+ifdef::backend-pdf[]
+:source-highlighter: coderay
+endif::[]
+:data-uri:
+:hide-uri-scheme:
+:stem: latexmath
+:footnote:
+:xrefstyle: short
+
+[preface]
+== List of figures
+list-of::image[hide_empty_section=true, enhanced_rendering=true]
+
+[preface]
+== List of tables
+list-of::table[hide_empty_section=true, enhanced_rendering=true]
+
+[preface]
+== List of listings
+list-of::listing[hide_empty_section=true, enhanced_rendering=true]
+
+[WARNING]
+.This document is in the link:http://riscv.org/spec-state[Development state]
+====
+Expect potential changes. This draft specification is likely to evolve before
+it is accepted as a standard. Implementations based on this draft
+may not conform to the future standard.
+====
+
+[preface]
+== Copyright and license information
+This specification is licensed under the Creative Commons
+Attribution 4.0 International License (CC-BY 4.0). The full
+license text is available at
+https://creativecommons.org/licenses/by/4.0/.
+
+Copyright 2025 by RISC-V International.
+
+[preface]
+include::contributors.adoc[]
+
+include::intro.adoc[]
+include::chapter2.adoc[]
+
+// The index must precede the bibliography
+include::index.adoc[]
+include::bibliography.adoc[]