Skip to content

Put the title page and front matter first in the nav - #172

Merged
Bill Traynor (wmat) merged 1 commit into
mainfrom
fix/page-titles
Sep 11, 2026
Merged

Bill Traynor (wmat) merged 1 commit into
mainfrom
fix/page-titles

Conversation

@wmat

Copy link
Copy Markdown
Collaborator

Follow-up to #171. That PR merged before this commit arrived, so it needs its own.

Puts the nav in the same order as the template and the PDF: title page, copyright,
contributors, introduction
, then the chapters.

What changes

nav.adoc now follows the template's structure: the title page (index.adoc) is the
top-level entry, and copyright, contributors, the introduction and 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. MIGRATION.md Step 9 asks for one
    ("landing page first").
  • Copyright and contributors were last. Restore the template's front and back matter #169 put them there on the stated grounds
    that the central playbook numbers this component's chapters by line number in this
    file. That was never checked, and it's 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 claiming otherwise is replaced by 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 is dropped. The title-page entry,
    labelled with the component title, takes its place, as in the template.
  • The guide taught the wrong nav. The example in antora-structure.adoc — 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.

Verification

  • Same page set as before, plus the title page.
  • Antora log unchanged: one pre-existing graphviz warning, no errors.
  • Rendered sidebar: RISC-V Authoring and Editing Guide › Copyright and license
    information › Contributors › Introduction › …
    , nested under the title page.

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
Signed-off-by: Bill Traynor <wmat@riscv.org>
@wmat
Bill Traynor (wmat) merged commit 488f5db into main Sep 11, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant