Convert the site documents from APT to Markdown

[slachiewicz]

Part of codehaus-plexus/.github#58. All 65 APT pages. Unblocked by #21, which put this repo on parent 26 — without that, Spotless destroys the front matter.

Two commits — please merge or rebase, don't squash, so git log --follow survives 65 renames.

No URL changes. x.apt and x.md both produce x.html. Nothing moved, nothing was deleted. This is almost entirely the retired IoC documentation, which is deep-linked from fifteen years of blog posts and Stack Overflow answers.

Verification

Built the site before and after and diffed every page through the normaliser — title, author and date metadata, visible text, and every link target:

IDENTICAL: 66 of 73
DIFFERING: 7

Internal link checking finds the same five pre-existing broken links as before and no new ones — the ones already listed in #17.

Converter defects found and repaired

doxia-converter 1.3. Every one of these is invisible in the Markdown and only appears in the HTML, which is why the before/after diff is the whole method rather than a formality.

Multiple authors — the worst of them. An APT header may list several authors. The converter emits the first inline and the rest on bare continuation lines:

title: Developer Guide - Table of Contents
author: Michal Maczka
Rahul Thakur
date: 2006-06-17

A parser that stops at the second author loses everything after it — including the date — which then renders as body text. Ten pages were affected. Repeated YAML keys don't work either: the last one silently wins, so two authors became one. They're emitted as a list now, and both <meta name="author"> tags come out.

The rest:

Defect	Effect
Front matter without --- fences	Page loses title and author entirely
Headings shifted down one level	APT section renders <h1>, came out ##
Source indentation preserved	Prose became indented code blocks
Ordered lists emitted as 1 Item	No period, so it rendered as literal text, not a list
{{{#Anchor}}} → [](Anchor)	Lost the label and the leading #
Emphasis emitted as ** text **	CommonMark needs no padding; rendered as literal asterisks
Backslashes left in code spans and before ~	${...} rendered as $\{...\}

The cleanup is scripted, so it's reproducible rather than 65 hand edits.

The seven that differ, and why I'm not chasing them further

None loses content.

1. index.html — the only difference is -- rendering as an en dash. Flexmark's typography, applied to prose. I'd call it an improvement.
2. javadoc-tags-reference — Doxia normalises @ in anchor ids, so #@plexus.component became #a.40plexus.component. Self-consistent, so the on-page links work; an external deep link to the old fragment would not. Worth a second opinion — I can pin explicit anchors if you'd rather.
3. component-configuration — the APT anchors rendered as links with no visible text. The conversion gives them their name as a label. A change, and I think a good one.
4. building-applications/index — three literal [ ] pairs where APT's definition-list syntax wasn't recognised.
5. configuration/index — an empty anchor link went from href="#" to href="". Useless either way.
6. component-descriptor-creator — one table cell merged into its neighbour.
7. 07_02_from_a_plexus_application — the converter split an inline XML snippet across code spans, producing `jar</packaging` ``. Fixed by hand, as one malformed line did not justify another global rule.

Items 4–6 are cosmetic and confined to the retired guides. Happy to fix them if you disagree — I stopped because the cost of another regex outweighed the benefit on pages nobody edits.

Next

You asked for convert first, improve later. This is the convert half, deliberately faithful — no rewording, no restructuring, no link fixing, so the diff is reviewable as a format change. The improvement pass is a separate PR.