Pages without a level-0 title render as "Untitled": two samples ship that way, and no check catches it #155

Summary

Antora takes a page's title from its level-0 = Title line. A page that opens with
== (or with anything else) is listed as "Untitled" — in the browser tab and
wherever the UI prints the page title.

Two of the template's six sample pages ship that way, and nothing in the template
catches it when authors do the same with their own chapters.

Evidence

On the template's own Pages site (spec-sample/dev):

Every repo seeded from the template inherits this unchanged: fake-spec,
spec-template-test, template-guinea-pig and template-pippin all have an untitled
index page, and the two with a copyright page have it untitled too.

Why the samples aren't the whole problem

The rule is stated in ANTORA.md and MIGRATION.md Step 7, but not in README.adoc,
and nothing enforces it — validate-content-source.yml has no title check, so the build
stays green.

riscv/docs-dev-guide went through the migration and came out with 17 of 18 pages
untitled, because its chapters were written as == sections of one master document —
exactly what an existing spec repo will have when it migrates. The fix there is commit
riscv/docs-dev-guide@67e1d0e: promote every heading one level and add leveloffset=+1 to
each include in the assembler. The standalone HTML's rendered body text is unchanged by it.

Proposed

1. A CI check in validate-content-source.yml

#!/usr/bin/env bash
# Fail if any Antora page does not open with a level-0 `= Title`.
# Antora takes the page title from that line; without it the page is
# listed as "Untitled". Leading blank lines, // comments, //// comment
# blocks, and [attribute] / [[anchor]] lines are allowed above the title.
set -uo pipefail
dir="${1:-modules/ROOT/pages}"
bad=0
for f in "$dir"/*.adoc; do
  first="$(awk '
    /^\/\/\/\/+[[:space:]]*$/ { c = !c; next }
    c { next }
    /^[[:space:]]*$/ || /^\/\// || /^\[.*\][[:space:]]*$/ { next }
    { print; exit }' "$f")"
  if [[ ! "$first" =~ ^=\ [^[:space:]] ]]; then
    echo "::error file=$f::no level-0 title (first content line: ${first:0:60})"
    bad=1
  fi
done
exit "$bad"

Tested against three trees. Its result matches the live "Untitled" count exactly in each:

It can't land on its own: it fails on every repo's index.adoc until item 3 is
decided. Either land it with item 3, or have it skip the start_page for now.

2. copyright.adoc: move [preface] into the assembler

Make the page open with = Copyright and license information and put [preface] ahead of
its include, as the assembler already does for contributors. The style still lands on
the same heading in the PDF. docs-dev-guide@67e1d0e does exactly this, and likewise for
[bibliography].

3. index.adoc: needs a decision

The cover puts the logo above the heading, and the shared UI renders an <h1> from the
page title unconditionally — partials/article.hbs in riscv-antora-only-ui:

{{#with page.title}}
<h1 id="page-title" class="page">{{{this}}}</h1>
{{/with}}

There's no notitle escape, so giving index.adoc a level-0 title puts the heading
above the logo. The options I can see:

• Accept it: title first, then logo. Simplest; changes the cover's look.
• UI change: let a page attribute (e.g. :notitle: or a cover role) suppress that
  <h1>, so the cover keeps its layout and still gets a <title>.

Context

Found while checking riscv/docs-dev-guide after it adopted the template in doc mode. The
downstream half — its own 16 pages and its authoring instructions — is riscv/docs-dev-guide#171.
index.adoc was left alone so it can follow whatever is decided here.