From 7c6d3ab37fb214b06ce33117f87c180f7dffd48c Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Fri, 11 Sep 2026 13:57:26 -0400 Subject: [PATCH] Put the title page and front matter first in the nav Match the template's nav.adoc: the title page (index.adoc) is the top-level entry, and copyright, contributors, the introduction and then the chapters are nested under it, in that order. The PDF already opens title page, copyright, contributors, Chapter 1. The nav had no title-page entry at all, which MIGRATION.md Step 9 asks for ("landing page first"), and carried copyright and contributors at the end. They went there in #169 on the stated grounds that the central playbook numbers this component's chapters by line number in this file. That was never checked and is wrong: docs-dev-guide's content source is commented out in both antora.riscv.org and antora-dev.riscv.org, and neither has a numbering rule for docs-guide. The comment asserting it is removed. In its place is the template's own header comment, which warns about line-number coupling in general terms -- true once this guide is registered centrally. The `.Authoring and Editing RISC-V Specs` nav title goes too: the title-page entry, labelled with the component title, takes its place, as in the template. antora-structure.adoc: the guide's example nav -- the one template users copy -- listed spec-sample.adoc as the landing page (the template's is index.adoc), put contributors after the chapters, and left out copyright. It now matches the template's nav.adoc entry for entry. Verified: Antora builds with the same single pre-existing warning and no errors; the rendered sidebar reads RISC-V Authoring and Editing Guide > Copyright and license information > Contributors > Introduction > ..., nested under the title page. Co-Authored-By: Claude Opus 5 Signed-off-by: Bill Traynor --- modules/ROOT/nav.adoc | 52 ++++++++++++++---------- modules/ROOT/pages/antora-structure.adoc | 5 ++- 2 files changed, 33 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 87aea65..d398bc1 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,22 +1,30 @@ -.Authoring and Editing RISC-V Specs -* xref:intro.adoc[Introduction] -* xref:authoring.adoc[AsciiDoc authoring for RISC-V contributors] -* xref:install-tools.adoc[Installing Asciidoctor and using AsciiDoc] -* xref:author-quickstart.adoc[Template Quickstart: Writing a Spec] -* xref:antora-structure.adoc[Antora directory structure] -* xref:a_few_basics.adoc[AsciiDoc basics] -* xref:index_bib.adoc[Index and Bibliography] -* xref:graphics.adoc[Graphics] -* xref:vale.adoc[Vale at RISC-V] -* xref:style-guidelines.adoc[RISC-V Style Guidelines] -* xref:writing.adoc[Best Practice] -* xref:word-usage.adoc[Word Usage Guide] -* xref:linting.adoc[Linting] -* xref:build-infrastructure.adoc[Build Infrastructure] -* xref:bibliography.adoc[Bibliography] -// Back matter. Appended rather than placed up front (where the template puts -// them) so the chapter line numbers above do not shift: the central playbook's -// numbering_rules entry for this component keys chapters off LINE NUMBERS in -// this file. See MIGRATION.md Step 11. -* xref:contributors.adoc[Contributors] -* xref:copyright.adoc[Copyright and license information] +// Navigation file for Antora +// https://docs.antora.org/antora/latest/navigation/ +// +// Update this file to reflect your specification's chapter structure. +// +// SECTION NUMBERING: the RISC-V central playbook assigns chapter numbers by the +// LINE NUMBER of each xref entry below, via its numbering_rules (see ANTORA.md, +// "Section numbering"). If you add, remove, or reorder entries here -- or edit +// these header comments -- the line numbers shift, so the matching rule in the +// central playbook (antora.riscv.org) MUST be updated, or site numbering drifts. +// To update number, open an issue at https://github.com/riscv-admin/antora-dev.riscv.org + +* xref:index.adoc[RISC-V Authoring and Editing Guide] +** xref:copyright.adoc[Copyright and license information] +** xref:contributors.adoc[Contributors] +** xref:intro.adoc[Introduction] +** xref:authoring.adoc[AsciiDoc authoring for RISC-V contributors] +** xref:install-tools.adoc[Installing Asciidoctor and using AsciiDoc] +** xref:author-quickstart.adoc[Template Quickstart: Writing a Spec] +** xref:antora-structure.adoc[Antora directory structure] +** xref:a_few_basics.adoc[AsciiDoc basics] +** xref:index_bib.adoc[Index and Bibliography] +** xref:graphics.adoc[Graphics] +** xref:vale.adoc[Vale at RISC-V] +** xref:style-guidelines.adoc[RISC-V Style Guidelines] +** xref:writing.adoc[Best Practice] +** xref:word-usage.adoc[Word Usage Guide] +** xref:linting.adoc[Linting] +** xref:build-infrastructure.adoc[Build Infrastructure] +** xref:bibliography.adoc[Bibliography] diff --git a/modules/ROOT/pages/antora-structure.adoc b/modules/ROOT/pages/antora-structure.adoc index 7a7e7b5..c7d1336 100644 --- a/modules/ROOT/pages/antora-structure.adoc +++ b/modules/ROOT/pages/antora-structure.adoc @@ -72,10 +72,11 @@ The `nav.adoc` file defines the navigation sidebar shown in the Antora site. [source,adoc] ---- -* xref:spec-sample.adoc[RISC-V Example Specification] +* xref:index.adoc[RISC-V Example Specification] +** xref:copyright.adoc[Copyright and license information] +** xref:contributors.adoc[Contributors] ** xref:intro.adoc[Introduction] ** xref:chapter2.adoc[The Second Chapter] -** xref:contributors.adoc[Contributors] ** xref:bibliography.adoc[Bibliography] ----