Template Quickstart: Writing a Spec

This guide is for a specification author who has a GitHub repository that was created from the docs-spec-template repository. By using this template, you can single source your content for both PDF and the HTML output. You can use the GitHub repository actions to create build versions, interim releases, and milestone releases. Finally, you can build both the PDF and Antora HTML output locally by running the makefile and npm commands.

Before you begin

When your GitHub repository was created, the "spec-sample" identity is still baked in. Rename the files and update the metadata to reflect your spec’s identity.

Rename your files

The following table shows the files that you need to edit.

What File Change

What	File	Change
Component name (site path)	`antora.yml` → `name:`	`spec-sample` → your short name (e.g. `zilch`)
Component title	`antora.yml` → `title:`	Your spec’s title
Component name HTML	`antora-playbook.yml` (lines 16)	Change `title: RISC-V Specification` to be `title: RISC-V <your title>`
Component title HTML	`antora-playbook.yml` (lines 16)	Change `start_page: spec-sample::index.adoc` to be `start_page: <your short name>::index.adoc`
HTML index file	`modules/ROOT/pages/index.adoc` (~line 27)	Change `RISC-V Example Specification (Zexmpl)` to be the name of your spec. Do not edit anything else in this file.
HTML navigation file	`modules/ROOT/nav.adoc` (~line 13)	Change `RISC-V Example Specification` to be the name of your spec. This is the name that will appear in HTML navigation.
Book header file (PDF master document)	`src/spec-sample.adoc`	Rename the file; the Makefile derives the PDF name from its basename
Makefile source pointer	`Makefile` → `DOCS :=`	Point at your renamed header file
Author list	`src/spec-sample.adoc` (lines 1-2)	Your title and author list
README title	`README.adoc`	Your spec

Component name (site path)

antora.yml → name:

spec-sample → your short name (e.g. zilch)

Component title

antora.yml → title:

Your spec’s title

Component name HTML

antora-playbook.yml (lines 16)

Change title: RISC-V Specification to be title: RISC-V <your title>

Component title HTML

antora-playbook.yml (lines 16)

Change start_page: spec-sample::index.adoc to be start_page: <your short name>::index.adoc

HTML index file

modules/ROOT/pages/index.adoc (~line 27)

Change RISC-V Example Specification (Zexmpl) to be the name of your spec. Do not edit anything else in this file.

HTML navigation file

modules/ROOT/nav.adoc (~line 13)

Change RISC-V Example Specification to be the name of your spec. This is the name that will appear in HTML navigation.

Book header file (PDF master document)

src/spec-sample.adoc

Rename the file; the Makefile derives the PDF name from its basename

Makefile source pointer

Makefile → DOCS :=

Point at your renamed header file

Author list

src/spec-sample.adoc (lines 1-2)

Your title and author list

README title

README.adoc

Your spec

When a PDF file is built, the full title is derived from the short name, the version, and the build date (<short>-vX.Y-YYYYMMDD.pdf) automatically.

As a reminder, be sure to update the copyright.adoc file and the `contributors.adoc file with the same information that you update in the book header file.

Initialize the docs-resources repo

The docs-resources repo contains common utilities, graphics, and styling. Before you can use this repository, you must initialize it with the following command:

git submodule update --remote --init

After your submodule populates locally, you can use the repo contents to build your content locally.

Understand file structure

Create your chapter content .adoc files in the modules/ROOT/pages/ location. Both the PDF and the HTML read these same files. The PDF is assembled by using the book header file (src/<your-spec>.adoc), which uses include:: references to each chapter .adoc file. Start each chapter file with a level-0 title (= Chapter title), and include it in the book header file with leveloffset=+1 so that title becomes a chapter in the PDF. A chapter file without a level-0 title is listed as "Untitled" on the HTML site. The HTML site navigation uses a navigation file (modules/ROOT/nav.adoc) to build HTML content. Update both of these files to keep the PDF and HTML content in synch. Otherwise, the source files remain the same for both PDF and HTML output.

modules/ROOT/images. (1)
  risc-v_logo.svg
modules/ROOT/pages/
  index.adoc          (2)
  intro.adoc          (3)
  chapter2.adoc
  contributors.adoc   (4)
  copyright.adoc      (5)
  bibliography.adoc    (6)
modules/ROOT/resources/riscv-spec.bib   (7)
modules/ROOT/nav.adoc        (8)
src/spec-sample.adoc                    (9)

1	Images used in the spec. These are referenced from the chapter files and included in both PDF and HTML output.
2	Site landing / cover page. HTML-only — not part of the PDF. Follow the instructions in this file to update the content.
3	The introduction chapter. Becomes "Chapter 1" in the PDF.
4	Front matter that lists contributors. Included in both PDF and HTML: the site navigation renders it as a page, and the PDF assembler includes it as a `[preface]` ahead of the first chapter. Follow the instructions in this file to update the content.
5	Copyright and license information. Included in both PDF and HTML, the same way as the contributors file. Follow the instructions in this file to update the content.
6	Bibliography main page. Included in both PDF and HTML and uses the bibliography database (`riscv-spec.bib`) to render the references.
7	Bibliography database.
8	HTML navigation file — Update references to your chapter files here. This is the site navigation that builds the HTML output.
9	Book header file — Update references to your chapter files here. This is the PDF master document that assembles the PDF from the chapter files.

You must add files to both the nav.adoc file and the book header file (your-spec-name.adoc file in the src directory). If you miss an include:: entry in the book header file and the chapter is rendered in HTML, but missing from the PDF. Miss an xref: entry in the nav.adoc file and the chapter appears in the PDF but absent from the HTML. Be sure to update both together.

Do not add PDF-only constructs or styling to the content chapter files. These types of changes are included in only the book header file. HTML styling is included in the Antora playbook as well as the Antora UI repository.

Building your content locally

To build and view your content locally, run the following commands in your local repository. Start your docker instance before running these commands.

make                          # ARC PDF (+ HTML) into build/  (Docker-based)

npm install                   # once: Antora + kroki/mathjax preview extensions
docker compose up -d kroki    # local diagram server on :9870
npm run preview               # builds the site into build/site/
docker compose down           # stop Kroki when done

Note that your Citations and bibliography::[] render as raw text locally. The ASAM bibliography extension exists only in the central playbook. Check citations in the make PDF or on the HTML development site.

To open your website locally, go to the build folder in your local specification directory and open the index.html file.

GitHub Action builds

When you build your spec on GitHub, whether you are creating a PR or merging directly to main, the Actions workflow runs several actions, including building a PDF. It will not, however, increment your PDF version.

Understanding versioning

Versions are updated by using the Version-bot action in GitHub. After you run the Version-bot, a PR is created to update the version in the antora.yml file. Do not update the version manually; always run the Version-bot to change the version. Merge the Stamp Antora site version PDF as soon as possible.

[%header,cols="1,1,1"]
|===
|Version floor
|Phase
|Change control

|v0.0
|draft-and-development
|Everything subject to change

|v0.6
|development-complete
|(same notice text)

|v0.8
|stabilized
|Limited scope changes

|v0.9
|frozen
|Critical issues only

|v0.99
|ratification-ready
|Ratification-blocking only

|v1.0
|ratified
|No changes; follow-on extension only. Only members of the RISC-V team can create a ratified version of a specification.
|===

Ratification ready

When your spec development is complete and ratified, the RISC-V team creates a ratified version and publishes the document in the Ratified Specifications library.