Give every chapter page a level-0 title

modules/ROOT/pages/a_few_basics.adoc

@@ -1,5 +1,5 @@
 [[a_few_basics]]
-== AsciiDoc basics
+= AsciiDoc basics
 
 AsciiDoc is fully documented, and its documentation is actively maintained. This document has information about AsciiDoc markup to get you started.
 
@@ -18,13 +18,13 @@
 Send questions to help@riscv.org.
 ====
 
-=== Paragraphs
+== Paragraphs
 
 In AsciiDoc, normal paragraphs do not require markup.
 
 To create a new paragraph, put a space after the earlier line of text and continue.
 
-==== Basics of blocks and indents
+=== Basics of blocks and indents
 
   If you add an indent, your indented text becomes a block like this.
 
@@ -57,9 +57,9 @@
 
 See <<blocks_notes_markers>> for additional information about blocks.
 
-=== Headers
+== Headers
 
 When you author in AsciiDoc, you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, Asciidoctor throws an error.
 
 The following example is a valid sequence of headers.
 
@@ -87,11 +87,11 @@
 
 NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repository) trigger auto-generation of Appendix prefixes and of the Index (among other things).
 
-=== Lists
+== Lists
 
 Create unordered lists with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list.
 
-==== Unordered list
+=== Unordered list
 
 To create an unordered list, place a `*` and a space before an item. Put each new list item on a new line. Add a space between any supporting text at the beginning of a list.
 
@@ -107,10 +107,10 @@
 Example output:
 
 * Priv
 * Unpriv
 * Debug
 
-==== Ordered list
+=== Ordered list
 
 To create an ordered (numbered) list, place a `.` and a space before an item. Put each new list item on a new line. Add a space between any supporting text at the beginning of a list.
 
@@ -124,10 +124,10 @@
 Example output:
 
 . Priv
 . Unpriv
 . Debug
 
-==== Nested list
+=== Nested list
 
 To create a nested unordered list, use `** ` before the nested item.
 
@@ -181,7 +181,7 @@
 .. second numbered item
 * another bullet
 
-==== Add a title to a list
+=== Add a title to a list
 
 Titles can help introduce your list content.
 
@@ -197,17 +197,17 @@
 
 .Ordered list
 . Priv
 . Unpriv
 . Debug
 
-=== Hyperlinks and cross references
+== Hyperlinks and cross references
 
 Asciidoctor automates some linking as follows:
 
 * Recognizes hyperlinks to Web pages and shortens them for readability.
 * Automatically creates an anchor for every section and discrete heading.
 
-==== Hyperlinks
+=== Hyperlinks
 
 To create highlighted links, use the pattern in the following example:
 
@@ -219,7 +219,7 @@
 You can set https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[attributes for your external links]
 
 
-==== Cross references
+=== Cross references
 
 Use macros for cross references (links within a document) as in the following example:
 
@@ -236,12 +236,12 @@
 
 
 [[tables_symbols_math]]
-=== Tables
+== Tables
 
 By using tables, you can group information into logical units, which can make the infromation presented easier to understand.
 
 [[tables-gen]]
-==== General rules for tables
+=== General rules for tables
 Follow these general rules when you create a table.
 
 * Avoid tables in the middle of lists.
@@ -256,7 +256,7 @@
 *Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph.
 ====
 
-==== Simple table
+=== Simple table
 
 The following example shows a simple table with 2 rows and 2 columns. To indicate a new row, put a empty line between them.
 
@@ -283,7 +283,7 @@
 |Cell in column 2, row 2
 |===
 
-==== Adding table headers
+=== Adding table headers
 
 Headers can add additional information to your table, making them easier to understand.
 
@@ -326,7 +326,7 @@
 |Cell in col 3, row 2
 |===
 
-==== Table captions
+=== Table captions
 
 The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repository sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. You can set captions for tables, blocks, and illustrations. If you do not offer a caption, Asciidoctor defaults to the _basic_ cross-reference style.
 
@@ -364,7 +364,7 @@
 |===
 
 
-==== AsciiDoc tables from CSV data.
+=== AsciiDoc tables from CSV data.
 
 You can also create AsciiDoc tables directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly:
 
@@ -446,9 +446,9 @@
 3+|100|1|1|1 8+|    field        2+| 00  | mnemonic4
 |===
 
-=== Unicode symbols
+== Unicode symbols
 
 For PDFs, five-digit unicode symbols generally do not work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it is Prawn that has the problems.
 
 Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful:
 
@@ -505,12 +505,12 @@
 |===
 
 
-=== Mathematical notations
+== Mathematical notations
 
 WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations are displayed small and center vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally is displayed as a superscript. For this reason, always use viable options such as _italics_ or unicode (see <<Unicode symbols>>).
 
 
-==== Superscripts and subscripts
+=== Superscripts and subscripts
 
 To indicate a superscript, enclose the string for the superscript in carets as in the following example:
 
@@ -555,7 +555,7 @@
 of a shopping list, but I don't think the local bodega sells
 E=mc^2^," Lazarus replied.
 
-==== Latexmath
+=== Latexmath
 
 You can make use of LaTeX notation as in the following:
 
@@ -569,10 +569,10 @@
 
 [TIP]
 ====
 Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical renders symbols within the build process. For this reason, avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible.
 ====
 
-==== Stem content
+=== Stem content
 
 The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output.
 
@@ -596,7 +596,7 @@
 For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf.
 
 [[blocks_notes_markers]]
-=== Admonition blocks
+== Admonition blocks
 
 Five types of standard link:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonition blocks] are available in AsciiDoc. RISC-V uses these five types with the default icons.
 
@@ -630,7 +630,7 @@
 * Do not include results, steps, or prerequisites in admonitions.
 * Make your admonition clear and concise.
 
-==== Single paragraph admonition
+=== Single paragraph admonition
 
 For a single paragraph admonition, use a double colon:
 
@@ -643,7 +643,7 @@
 
 NOTE: Note content.
 
-==== Admonition blocks
+=== Admonition blocks
 
 An admonition block can contain any AsciiDoc content.
 
@@ -674,7 +674,7 @@
 * Make your admonition clear and concise.
 ====
 
-==== Admonition with a title
+=== Admonition with a title
 
 You can add a title to your admonition block.
 
@@ -695,7 +695,7 @@
 *Be aware that RLB introduces a security vulnerability if you set it after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It does not make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*.
 ====
 
-==== RISC-V admonition icon colors
+=== RISC-V admonition icon colors
 
 The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <<custom-color-icons>>.
 
@@ -722,7 +722,7 @@
 |===
 
 
-=== Code blocks
+== Code blocks
 
 AsciiDoc enables code blocks that support syntax highlighting.
 
@@ -787,7 +787,7 @@
 ....
 
 
-=== Change bars
+== Change bars
 
 Change indicators within text files are exceedingly useful and also can be equally complex to implement. Please consider the fact that much of the software programming for Git revolves around handling various kinds of change indicators.
 
@@ -800,7 +800,7 @@
 - Git features.
 - a few procedures associated, specifically, with Git updates.
 
-==== Indicate changes
+=== Indicate changes
 
 Indicators for the changed lines must be inserted manually:
 
@@ -826,7 +826,7 @@
 == [.Changed]#SELECT clause#
 ----
 
-==== Check for changed lines before a `git commit`
+=== Check for changed lines before a `git commit`
 
 You can double check for all changed lines before committing by using this pattern:
 
@@ -846,9 +846,9 @@
 ----
 
 
-=== Footnotes
+== Footnotes
 
 AsciiDoc has a limitation in that footnotes appear at the end of each chapter. Asciidoctor does not support footnotes appearing at the bottom of each page.
 
 You can add footnotes to your presentation using the footnote macro. If you plan to reference a footnote more than once, use the footnote macro with a target that you identify in the brackets.
 
@@ -877,7 +877,7 @@
 
 Another outrageous statement.footnote:disclaimer[]
 
-=== Sidebars
+== Sidebars
 
 Sidebars provide for a form of commentary.
 

modules/ROOT/pages/antora-structure.adoc

@@ -1,9 +1,9 @@
 [[antora-structure]]
-== Antora repository structure
+= Antora repository structure
 
 RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables Antora to assemble individual specification repositories into the RISC-V documentation site while also supporting a standalone PDF and HTML build using `make`.
 
-=== Repository layout
+== Repository layout
 
 A specification repository has the following top-level files and directories:
 
@@ -29,12 +29,12 @@
 <4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site.
 <5> Images: Symlink to `docs-resources/images` so Antora can find shared images.
 <6> Pages directory: all AsciiDoc source files live here.
 <7> Resources directory: resource files that are not asciidoc or images such as the bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute.
 <8> Partials directory: 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
+== antora.yml
 
 The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor] and 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) that Antora uses to assemble the documentation site.
 
 [source,yaml]
 ----
@@ -54,21 +54,21 @@
 name: debug
 title: Debug Specification
 
-=== modules/ROOT/pages/
+== 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).
+. Create the `.adoc` file in `modules/ROOT/pages/`. Start it with a level-0 title, `= Chapter title`. Antora uses that line as the page title, so a page that starts with `==`, or has no title, is listed as "Untitled" on the site.
+. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build), with a level offset: `include::../modules/ROOT/pages/my-chapter.adoc[leveloffset=+1]`. The offset turns the page's level-0 title into a chapter in the PDF. Without it, the PDF gets a second document title.
 . Add an `xref:` entry for it in `modules/ROOT/nav.adoc` (for the Antora site build).
 
-=== modules/ROOT/nav.adoc
+== modules/ROOT/nav.adoc
 
 The `nav.adoc` file defines the navigation sidebar shown in the Antora site.
 
 [source,adoc]
 ----
@@ -81,16 +81,16 @@
 
 Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the left navigation order in the HTML version in the RISC-V Specifications Library.
 
-=== modules/ROOT/images/
+== modules/ROOT/images/
 
 Antora locates images in the module directory tree. Store images used in the specification in the images directory.
 
 [[dev-playbook]]
-=== Publishing to the RISC-V documentation site
+== Publishing to the RISC-V documentation site
 
 A central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org] assembles the RISC-V documentation site from all specification repositories. 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
+=== Naming your branch
 
 By convention, name Antora-ready branches with the version and an `-antora` suffix:
 
@@ -99,9 +99,9 @@
 v20250312-antora
 ----
 
 Create this branch from your specification's release tag or working branch after the Antora directory structure is in place.
 
-==== Adding a content source
+=== 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:
 
@@ -118,7 +118,7 @@
 
 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 has symlinks.
 
-==== Adding numbering rules
+=== Adding numbering rules
 
 The playbook uses custom extensions to number chapters and appendixes 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 from a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add a single entry in the 'nav_numbering_extension` block:
 
@@ -137,16 +137,16 @@
 <4> The range of nav entries (top-level `*` items in `nav.adoc`) to number as 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 through 4.
 <5> Omit this line entirely if your specification has no appendixes.
 
-==== Submitting the pull request
+=== 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 added.
 
 [[install-antora]]
-=== Installing Antora
+== Installing Antora
 
 You need Antora to run a local site preview. It requires Node.js version 18 or later. Once you install Node.js, install Antora globally:
 
 [source,cmd]
 ----