Follow-up to #494. The Antora build lands with zero errors but emits 13 warnings — all pre-existing content issues that the migration surfaced rather than introduced. Clearing them takes the site from "builds, with noise" to "builds clean".
The warnings
-
4× missing attribute references in `docs/modules/ROOT/pages/explanation/operator-design.adoc`:
- `{framework_name}` (3 occurrences)
- `{ksp_version}`
- `{dokka_version}`
- `{asciidoctorj_version}`
The original ops-docs design article was authored against an attributes block that got lost in an earlier edit. Fix: define the four attributes once at the component level in `docs/antora.yml` (`asciidoc.attributes`) so they flow to every page in the component.
-
6× section title out of sequence from pandoc markdown→asciidoc conversion:
- `skainet-for-ai.adoc:32,44,74,79,112` — expected level 2, got level 3
- `arduino-c-codegen.adoc:48` — expected level 3, got level 4
Pandoc preserved the source heading levels but dropped a wrapping level between them. Fix: re-level the offending sections one step up (=== → ==, ==== → ===) so the level sequence is strictly non-skipping.
-
1× kroki mermaid 400 on a large diagram in `docs/modules/ROOT/pages/tutorials/hlo-getting-started.adoc`:
The kroki.io GET URL with the encoded diagram payload exceeds their length limit and returns 400 for this specific diagram. The other mermaid diagrams in the repo render fine. Fix options:
- (A) Simplify the diagram (fewest nodes / shorter labels) until it fits the URL limit.
- (B) Switch the asciidoctor-kroki extension to a POST-based path — requires changing `kroki-fetch-diagram: true` configuration in `docs/antora-playbook.yml`.
- (C) Pre-render the diagram to an SVG asset committed alongside the page and reference it as `image::diagram.svg[]`.
Going with (B) first — single config change, fixes this and any future large diagram automatically. Fall back to (A) or (C) if POST isn't available in asciidoctor-kroki 0.18.
Success criterion
```
docker run --rm -v "$PWD:/antora" -w /antora \
skainet-antora:local docs/antora-playbook.yml 2>&1 | grep -c '"level":"warn"'
```
Should print `0`.
Out of scope
- Content rewrites of the docs themselves.
- UI customization (Antora bundle theme, branding).
- External link checking (separate issue).
- Moving the published site to a custom domain.
Follow-up to #494. The Antora build lands with zero errors but emits 13 warnings — all pre-existing content issues that the migration surfaced rather than introduced. Clearing them takes the site from "builds, with noise" to "builds clean".
The warnings
4× missing attribute references in `docs/modules/ROOT/pages/explanation/operator-design.adoc`:
The original ops-docs design article was authored against an attributes block that got lost in an earlier edit. Fix: define the four attributes once at the component level in `docs/antora.yml` (`asciidoc.attributes`) so they flow to every page in the component.
6× section title out of sequence from pandoc markdown→asciidoc conversion:
Pandoc preserved the source heading levels but dropped a wrapping level between them. Fix: re-level the offending sections one step up (
===→==,====→===) so the level sequence is strictly non-skipping.1× kroki mermaid 400 on a large diagram in `docs/modules/ROOT/pages/tutorials/hlo-getting-started.adoc`:
The kroki.io GET URL with the encoded diagram payload exceeds their length limit and returns 400 for this specific diagram. The other mermaid diagrams in the repo render fine. Fix options:
Going with (B) first — single config change, fixes this and any future large diagram automatically. Fall back to (A) or (C) if POST isn't available in asciidoctor-kroki 0.18.
Success criterion
```
docker run --rm -v "$PWD:/antora" -w /antora \
skainet-antora:local docs/antora-playbook.yml 2>&1 | grep -c '"level":"warn"'
```
Should print `0`.
Out of scope