Convert the site document from xdoc to Markdown - #101
Conversation
58d576d to
a77bec9
Compare
|
Parent 26 is released and is on Central, carrying I've deliberately not folded the parent bump into this PR — parent updates belong in their own PR, so this one stays a self-contained doc conversion, reviewable against the parent this repo is on today (25). That means the local Spotless exclusion here is still doing real work and should stay for now. Once this repo moves to parent 26 it becomes redundant and can be deleted — the comment in the POM says exactly that, so whoever does the bump has the context. No change needed here; CI is green on all nine matrix jobs. |
|
Parent 26 is out and carries this exclusion, so the local one here becomes redundant. I have Leaving this PR as it is for now: it is self-contained and mergeable against parent 25, which |
Git records a rename plus a rewrite in one commit as a delete and an add, which stops 'git log --follow'. Splitting the rename out keeps the history. Please merge or rebase rather than squash.
Converted with doxia-converter, then cleaned up: the 1.3 converter emits the front matter without its --- fences, which would render as literal text and lose the title and author, and it shifts every heading down one level. Verified by building the site before and after and diffing the normalised pages. Title, author, visible text and link targets are identical. Part of codehaus-plexus/.github#58
Without this, spotless rewrites the fence closing the YAML front matter block in src/site/markdown into a setext underline, which destroys the page's title and author. CI runs spotless:check and fails; a local build runs spotless:apply and silently corrupts the file. Configured in pluginManagement rather than build/plugins. The parent only declares Spotless inside its java17+ profile, because Spotless 3.x is compiled for Java 17, so declaring it unconditionally breaks the JDK 8 CI jobs. The released parent POM 25 does not carry this exclusion. Parent 26 does, so this can be dropped once 26 is out. Part of codehaus-plexus/.github#58
Parent 26 excludes src/site/markdown from the Markdown formatter, so the override added here is redundant. Removing the whole spotless entry rather than just the one exclude line: plugin configuration does not merge list elements, so a local <excludes> holding only target/** would replace the parent's list and quietly take the site exclusion with it.
|
Parent 26 has landed, so the local exclusion is gone. Worth noting how: I removed the whole Verified: the source |
a77bec9 to
e1701d5
Compare
1 participant
Part of codehaus-plexus/.github#58.
src/site/xdoc/index.xml→src/site/markdown/index.md. One page, converted withdoxia-converter.Two commits, please don't squash
The rename is deliberately separate from the rewrite. Git's rename detection is similarity-based, so a rename plus a content rewrite in one commit is recorded as a delete and an add, and
git log --followstops dead there. Merge or rebase rather than squash and the history survives.The converter output needed fixing
doxia-converter1.3 (2.0.0 doesn't exist on Central — only 1.0–1.3) gets two things wrong on xdoc input, both silent:---fences. Doxia's Markdown parser only looks for front matter when the file starts with---, so the output would have renderedtitle: Plexus Velocity Component / author: Olivier Lamyas literal body text — and the page would have lost its<title>and<meta name="author">entirely.<section>came out as##and<subsection>as###, where the original rendered<h1>and<h2>.Neither is visible in the Markdown; both only show up in the generated HTML.
Verified, not assumed
Built the site before and after, and diffed the normalised pages — title, author metadata, visible text and every link target:
Identical. Note this compares the
<head>as well as the body, which is the point — a body-only comparison would happily pass a page that had lost its author and title.While checking that, the diff caught two small edits I'd made without meaning to: I'd dropped the "A typical use:" lead-in and slipped an article into "creating a
VelocityComponentConfigurator". Both reverted — a format migration shouldn't smuggle in copy changes, and if the wording wants improving that's a separate PR.Safe here
The parent POM already excludes
**/src/site/markdown/**from Spotless, with a comment explaining that flexmark rewrites the fence closing a front matter block and destroys the metadata. This repo is on parent 25, so that's in effect — worth knowing before converting anything in a repo that isn't.The output URL is unchanged:
index.xmlandindex.mdboth produceindex.html.