diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..9dd378e --- /dev/null +++ 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 index 0ce4a3c..e63e2b0 100644 --- 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 index 404c214..5629fec 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -88,7 +88,7 @@ The following example is a valid sequence of headers. 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 @@ Either table renders with table headers. ==== 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 new file mode 100644 index 0000000..c2cf806 --- /dev/null +++ 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]. diff --git a/src/authoring.adoc b/src/authoring.adoc index 3e6b0dc..872e6d6 100644 --- a/src/authoring.adoc +++ b/src/authoring.adoc @@ -10,15 +10,24 @@ Asciidoctor toolchains: === RISC-V AsciiDoc authoring assets -Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes. +Please view the https://github.com/riscv/docs-spec-template[readme] in the docs-spec-template repo for information about the automated build processes. -The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[document] that takes you through a local install process that supports all of the required features for a local build. +The docs-spec-template repo contains assets such as fonts, styles, directory structure, and themes needed for RISC-V specifications. It uses an Antora-compatible directory structure with source files in `modules/ROOT/pages/`. See <> for a full description of the layout. -Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output by using the following command: +A https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[local build guide] takes you through the local install process that supports all of the required features. + +Although testing your markup by building a PDF is a good practice, you can catch many common errors by downloading Asciidoctor and building the HTML output using the following command from the repository root: + +[source,cmd] +---- +asciidoctor modules/ROOT/pages/spec-sample.adoc +---- + +Or more simply, using the Makefile: [source,cmd] ---- -asciidoctor book_header.adoc +make ---- === Writing diff --git a/src/build-infrastructure.adoc b/src/build-infrastructure.adoc index 9eb6cf3..8aa233f 100644 --- a/src/build-infrastructure.adoc +++ b/src/build-infrastructure.adoc @@ -4,6 +4,12 @@ Most RISC-V AsciiDoc documents use a `Makefile` to simplify the build process. F If Docker is already installed, the `Makefile` will invoke `docker` for the build process. Otherwise, it will build natively. +=== Source directory + +In the Antora-based template, AsciiDoc source files live in `modules/ROOT/pages/` rather than a flat `src/` directory. The `Makefile` sets `SRC_DIR := modules/ROOT/pages` accordingly. The entry point for the PDF and HTML build is `modules/ROOT/pages/spec-sample.adoc`. + +For a full description of the Antora directory structure and how to register your specification with the RISC-V documentation site, see <>. + As an author of a document, there are some conventions to be aware of: - The version, date, and state (draft, frozen, ratified) of the document should be specified in the `.adoc` file for that document via use of the `:revnumber:` and `:revremark:` keywords. An example usage is the following: @@ -69,3 +75,58 @@ errors. This can be adjusted by altering the `asciidoc` invocation in the `Makef This document repository currently adheres to all of these conventions, and may be a useful starting point for other specifications. + +[[spec-types]] +=== ISA vs. non-ISA specifications + +How a specification is authored and where it lives depends on whether it is an ISA or non-ISA specification. + +ISA specifications:: +Extensions to the RISC-V Unprivileged or Privileged ISA are authored as chapters within a branch or fork of the https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] repository. The specification state and revision information are set within the relevant chapter file(s) in that branch, consistent with the conventions of the ISA manual. + +Non-ISA specifications:: +All other RISC-V specifications are authored in their own autonomous GitHub repository, using the https://github.com/riscv/docs-spec-template[docs-spec-template] as the starting point. The repository layout, build infrastructure, and GitHub Actions workflows are all provided by the template. + +[[spec-lifecycle]] +=== Specification lifecycle + +RISC-V specifications progress through four defined states. The current state is set via the `:revremark:` attribute in the document header and is displayed on the cover page of every build. The canonical definitions of each state are maintained at https://riscv.org/spec-state[riscv.org/spec-state]. + +Draft:: +The specification is under active development. Everything is subject to change. Use `:revremark: This document is in the link:http://riscv.org/spec-state[Development state]` or simply `:revremark: Draft`. + +Stable:: +The specification is feature-complete but may still change in response to public review feedback. Use `:revremark: Stable`. + +Frozen:: +The specification has completed public review. Only critical bug fixes are permitted. Implementations based on this version may proceed at the implementer's risk. Use `:revremark: Frozen`. + +Ratified:: +The specification has been formally ratified by RISC-V International. No further changes will be made to this version. Use `:revremark: Ratified`. + +==== State advancement is manual + +State advancement is *not* automated. No process or workflow automatically promotes a specification from one state to the next. Authors must update `:revremark:` in the source document by hand, following approval through the appropriate RISC-V governance process. + +==== Non-ISA specifications: releasing a new state + +For non-ISA specifications, each state transition should be accompanied by a corresponding GitHub release so the published PDF is permanently associated with that state. The `build-pdf.yml` GitHub Actions workflow supports this via a manual `workflow_dispatch` trigger. + +To publish a release at a new state: + +. Update `:revremark:` in `modules/ROOT/pages/spec-sample.adoc` to the new state. +. Update `:revnumber:` to the appropriate version string. +. Commit and push the changes. +. In GitHub, navigate to *Actions → Create Specification Document → Run workflow*. +. Select the matching `revision_mark` (Draft, Stable, Frozen, or Ratified). +. Set `prerelease` and `draft` flags as appropriate. +. Run the workflow — it will build the PDF, create a git tag, and publish a GitHub release. + +[NOTE] +==== +The `revision_mark` selected in the workflow dispatch sets the `REVMARK` environment variable passed to `make`, which overrides `:revremark:` in the built PDF. Ensure the value you select matches what is set in the source document so the two are consistent. +==== + +==== ISA specifications: state within the ISA manual + +For ISA specifications, the specification state is not tracked via a standalone GitHub release workflow. Instead, the state is reflected within the chapter(s) of the relevant ISA manual — either the Unprivileged or Privileged specification — in the branch of https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] where the author is working. The state and revision information should follow the conventions established within that repository and be consistent with the overall state of the ISA manual branch. diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index 3e5238e..0b787a4 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -74,6 +74,8 @@ include::intro.adoc[] include::authoring.adoc[] +include::antora-structure.adoc[] + include::a_few_basics.adoc[] include::index_bib.adoc[] diff --git a/src/intro.adoc b/src/intro.adoc index d9c1255..ebcd357 100644 --- a/src/intro.adoc +++ b/src/intro.adoc @@ -17,3 +17,20 @@ RISC-V documentation contributors: - Create a Linux foundation ID with https://lfx.linuxfoundation.org/[LFX]. - Become a https://riscv.org/membership/[member of the RISC-V International] organization. + +[[getting-help]] +=== Getting help + +If you have questions about authoring, the build toolchain, or the Antora documentation site, the following resources are available: + +https://lists.riscv.org/g/sig-documentation[sig-documentation mailing list]:: +The primary venue for discussion about RISC-V documentation tooling, processes, and the Antora site. Post here for questions about the build infrastructure, the dev playbook, or contributing a new specification. + +mailto:help@riscv.org[help@riscv.org]:: +General RISC-V support address for questions that don't fit the mailing list. + +https://github.com/riscv/docs-dev-guide/issues[docs-dev-guide GitHub issues]:: +File an issue here if you find something incorrect or missing in this guide. + +https://github.com/riscv-admin/antora-dev.riscv.org/issues[antora-dev.riscv.org GitHub issues]:: +File an issue here for problems with the RISC-V Antora documentation site or the dev playbook.