[maven-3.9.x] Port the site documentation from APT to Markdown

[slachiewicz]

Ports the site documentation from APT to Markdown on maven-3.9.x, following #12682 on master.

All 24 pages converted; none left as APT. Three commits: a rename-only commit so git log --follow survives, then the conversion, then four readability edits kept separate for review. Please merge or rebase rather than squash.

Unlike the 4.0.x port, these 24 are a different and smaller set than master's 38, so this is a fresh conversion rather than a port of reviewed work.

Three traps that produce a clean build and a wrong page

Each was found by comparing rendered output, not by the build failing:

1. ${…} in flow text became an anchor. APT reads the braces as an anchor definition, so the baseline HTML rendered a visible $maven.home plus a stray <a id="maven.home">. The converter faithfully reproduced that breakage. 8 references repaired to literal code spans, matching master. Note the baseline was already wrong — this fixes it.
2. Bare file:// gets autolinked into <a href="file://">, which APT never produced. 8 occurrences in offline-mode escaped as file\://.
3. Empty table cells must be | |, not ||. String.split drops trailing empty fields, so a row ending in empty cells comes back short and ArtifactHandlerTest reads past its array end.

A fourth of the same kind: APT read the angle brackets of <developerConnection/> as italic markup and swallowed them, so the baseline rendered developerConnection/ italicised with no brackets. A code span restores them. That one arrived as a "readability" edit and turned out to be a fidelity fix.

Front matter kept

Master's conversion commit dropped it and a follow-up (096d59ec94) restored it; master carries it today. Keeping it from the outset preserves <meta name="author">, <meta name="date"> and the real page titles.

Verification

Full reactor mvn site before and after. Not the build succeeding — all 202 generated pages compared through a normaliser covering visible text, heading levels, table cells, list items, <pre> markers, link targets and page metadata.

202 compared, 0 missing, 2 differing — configuration-management and getting-to-container-configured-mojos, and the only differences are the intended repairs above. ArtifactHandlerTest passes; it was checked to be the only test in the branch that reads a site document.

Limits: the normaliser is text, structure markers and link targets, so a purely visual change — CSS, spacing, <b> versus <strong> — would not show, and no page was opened in a browser. Only ArtifactHandlerTest was run, not the full suite.

Two typos deliberately left alone

configuration-management reads "tweaking the the various files" and "analagous to the repository". Both are already fixed on 4.0.x and master. They are prose changes rather than conversion artefacts, so folding them in would have muddied the verification — happy to fix separately if wanted.

[gnodet]

Clean, thoroughly verified APT-to-Markdown conversion of all 24 site documentation pages on maven-3.9.x.

Key observations:

• Every deleted APT file has a matching Markdown replacement. No documentation pages lost.
• The only non-documentation change (ArtifactHandlerTest.java) is correct: path updated, method renamed, table parsing adapted for Markdown syntax.
• The four rendering traps documented in the PR description are all properly handled: ${...} converted to code spans, bare file:// escaped, empty table cells written as | |, and <developerConnection/> wrapped in code spans.
• Doxia macros correctly converted: APT %{snippet|...} becomes <!-- MACRO{snippet|...} -->.
• Minor cosmetic note: ~8 links have a leading space in link text (e.g. [ Settings Reference]), faithfully carried from APT syntax. Non-blocking.
• The three-commit structure (rename, convert, readability edits) supports git log --follow — respect the PR body's request to merge/rebase rather than squash.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet