153 add instructions for antora based spec template by wmat · Pull Request #154 · riscv/docs-dev-guide

Bill Traynor (wmat) · 2026-06-08T19:14:46Z

No description provided.

Signed-off-by: Bill Traynor wmat@riscv.org

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

…https://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

…ttps://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template Signed-off-by: wmat <wmat@riscv.org>

Kersten Richter (kersten1) · 2026-06-10T17:36:55Z

+      spec-sample.adoc
+      intro.adoc
+      chapter2.adoc
+      ...


add resources for bibliographies?

Also partials? I know I know - not many have wavedrom files. but still....

Yep, added that in with my last push.

Kersten Richter (kersten1) · 2026-06-10T18:15:56Z

+      chapter2.adoc
+      ...
+----
+<1> Antora component descriptor — identifies this repo as an Antora component.


This should probably be antora.yml - the antora component descriptor that identifies this repo as an Antora component.

But doesn't it do more than that? The antora.yml files contains all the config stuff for your build.

Expanded a bit with my last push.

Signed-off-by: Bill Traynor wmat@riscv.org

Kersten Richter (kersten1) · 2026-06-10T18:30:29Z

+    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.


it doesn't though? Maybe for local PDFs and the weird HTML, but you are implying that Makefile controls all the build stuff. Are we recommending that people use the Makefile for building PDFs still?

From Antora's POV the antora.yml is what makes it a component to be targetted. However, Make is still the way to build.

Kersten Richter (kersten1) · 2026-06-10T18:32:22Z

+<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.


it is? I also put shared images into the common assets folder in antora-dev.riscv.org

I thought you also put any graphics for the topic in here.

I guess some of this only applies to ISA content, which would already be convered by the fact that you branch the ISA repo to develop a new ISA spec.

Kersten Richter (kersten1) · 2026-06-10T18:33:05Z

+----
+<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.


docs-resources - Git submodule....

Not sure I understand what you mean.

Kersten Richter (kersten1) · 2026-06-10T18:33:47Z

+      ...
+    partials/                 <8>
+----
+<1> Antora component descriptor — identifies this repo as an Antora component and provides component metadata and configuration.


antora.yml - An antora component descriptor that identifies ...

Kersten Richter (kersten1) · 2026-06-10T18:34:10Z

+<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.


nav.adoc - The navigation file that defines....

Kersten Richter (kersten1) · 2026-06-10T18:34:58Z

+<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.


Pages directory - all AsciiDoc source files live here.

Kersten Richter (kersten1) · 2026-06-10T18:35:48Z

+<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.


doesn't this go in resources folder?

Kersten Richter (kersten1) · 2026-06-10T18:43:48Z

+<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[]`.


partials - optional directory ....

Kersten Richter (kersten1) · 2026-06-10T18:45:02Z

+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.


also becomes the name in the URL so be specific.

plus match what? I'm not sure what they are matching to?

Signed-off-by: Bill Traynor wmat@riscv.org

…ttps://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template

Co-authored-by: Kersten Richter <kersten@riscv.org> Signed-off-by: Bill Traynor <wmat@riscv.org>

Kersten Richter (kersten1) · 2026-06-10T19:59:12Z

+----
+<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.


they should be using some sort of version here though?

Kersten Richter (kersten1) · 2026-06-10T19:59:39Z

+<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`.


if they use the correct set up, this should always be the same.

Kersten Richter (kersten1) · 2026-06-10T20:03:21Z

+<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.


rather than at minimum, tell them to set the name, title, and version... Versions should be probably set as "frozen" "development" or "stable" or whatever we decide.

They should also include a page-group.

asciidoc:
attributes:
page-group: under-development

Kersten Richter (kersten1) · 2026-06-10T20:04:35Z

+[source,adoc]
+----
+* xref:spec-sample.adoc[RISC-V Example Specification]
+** xref:intro.adoc[Introduction]


very few of them actually nest. We just made them flat.

Kersten Richter (kersten1) · 2026-06-10T20:05:20Z

+
+=== 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.


sidebar is confusing because that makes me think of the right nav, which is controlled by the headings on the page.

Kersten Richter (kersten1) · 2026-06-10T20:05:46Z

+
+=== 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.


I don't think this is true.

Kersten Richter (kersten1) · 2026-06-10T20:07:09Z

+
+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/`.


for all jpg, png, and svg (with svg being the preferred). They don't need to include the risc-v logo because that is in the common-assets folder in antora-dev. But not sure how they are going to get that building locally.

Kersten Richter (kersten1) · 2026-06-10T20:08:48Z

+
+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


I'd just kill this. We want svg files. They can suck it up and start creating them.

Kersten Richter (kersten1) · 2026-06-10T20:09:47Z

+
 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:


and in the antora.yml file? not sure if we are using it that way though.

Kersten Richter (kersten1) · 2026-06-10T20:12:13Z

 [source,cmd]
 ----
-asciidoctor book_header.adoc
+make


I get errors.

and it crashes without finishing

Kersten Richter (kersten1) · 2026-06-10T20:16:46Z

+asciidoctor modules/ROOT/pages/spec-sample.adoc
+----
+
+Or more simply, using the Makefile:


it is even more simple to just let github build, as long as the repo is set up properly. Could we do that?

Bill Traynor (wmat) added 4 commits June 8, 2026 10:29

Changes for Antora instructions.

cb1ff8c

Signed-off-by: Bill Traynor wmat@riscv.org

More changes for Antora instructions.

ad7908a

Signed-off-by: Bill Traynor wmat@riscv.org

Updates for Antora.

dbe6198

Signed-off-by: Bill Traynor wmat@riscv.org

Adds a changelog.

e00e031

Signed-off-by: Bill Traynor wmat@riscv.org

Bill Traynor (wmat) linked an issue Jun 8, 2026 that may be closed by this pull request

Add instructions for Antora based spec template #153

Open

Bill Traynor (wmat) requested a review from Kersten Richter (kersten1) June 8, 2026 19:15

Bill Traynor (wmat) added 6 commits June 8, 2026 15:20

Adds a changelog.

1d4a918

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

:Merge branch '153-add-instructions-for-antora-based-spec-template' of …

0ca633d

…https://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template

More changes for Antora instructions.

928e994

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

Updates for Antora.

b33c164

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

Adds a changelog.

c54dc2d

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>

Merge branch '153-add-instructions-for-antora-based-spec-template' of h…

2de5e51

…ttps://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template Signed-off-by: wmat <wmat@riscv.org>

Kersten Richter (kersten1) reviewed Jun 10, 2026

View reviewed changes

Addressing feedback.

44d5608

Signed-off-by: Bill Traynor wmat@riscv.org

Kersten Richter (kersten1) reviewed Jun 10, 2026

View reviewed changes

Comment thread src/authoring.adoc Outdated

Bill Traynor (wmat) and others added 3 commits June 10, 2026 15:08

Addressing feedback.

0bf3294

Signed-off-by: Bill Traynor wmat@riscv.org

Merge branch '153-add-instructions-for-antora-based-spec-template' of h…

c82fa01

…ttps://github.com/riscv/docs-dev-guide into 153-add-instructions-for-antora-based-spec-template

Update src/authoring.adoc

d64a5a5

Co-authored-by: Kersten Richter <kersten@riscv.org> Signed-off-by: Bill Traynor <wmat@riscv.org>

Kersten Richter (kersten1) reviewed Jun 10, 2026

View reviewed changes


		=== 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.


		=== 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.


		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/`.


		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


		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:

Conversation

Bill Traynor (wmat) commented Jun 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants