Convert the site documents from xdoc to Markdown - #149
Conversation
|
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 has three defects that are invisible in the Markdown and only appear in the generated HTML: it emits the front matter without its --- fences, it shifts every heading down one level, and it keeps the source XML indentation, which turns prose into indented code blocks. Also excludes site sources from the Spotless markdown formatter. This is not optional: flexmark rewrites the fence closing a front matter block into a setext underline, which destroys the title and author. It happened during this conversion - the first build silently emptied all three pages. The released parent POM 25 does not carry this exclusion, and spotless.action defaults to apply outside CI. Verified by building the site before and after and diffing the normalised pages. Title, author, visible text and link targets are identical on all three. Part of codehaus-plexus/.github#58
Declaring the plugin in build/plugins forced it to run on every JDK. The parent only declares Spotless inside its java17+ profile, because Spotless 3.x is compiled for Java 17, so the JDK 8 CI jobs failed with 'has been compiled by a more recent version of the Java Runtime'. pluginManagement configures the plugin without declaring it, so the exclusion applies wherever the parent activates Spotless and JDK 8 builds are untouched.
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.
8bcc4f6 to
02d8c3c
Compare
|
Parent 26 has landed, so the local exclusion is gone. Worth noting how: I removed the whole Verified: the source |
1 participant
Part of codehaus-plexus/.github#58. Three pages:
index,apiusage,launcher.Two commits — please merge or rebase, don't squash. The rename is separate from the rewrite because git's rename detection is similarity-based; combined, it records as a delete plus an add and
git log --followstops there.The Spotless problem — worth reading even if you skim the rest
This conversion silently emptied all three pages on the first build. Not the metadata — the entire body. The generated
index.htmlcame out with nothing in it.Cause: the parent POM runs Spotless over
**/*.md, andspotless.actiondefaults toapplyoutside CI (theformatprofile activates on!env.CI). Flexmark then rewrites the fence that closes a YAML front matter block into a setext underline:That turns the front matter into a heading, and the page is destroyed.
Released parent POM 25 does not exclude site sources. Its markdown block excludes only
target/**. The exclusion exists in the unreleased26-SNAPSHOT, with a comment describing exactly this failure — so somebody already hit it — but nothing consuming parent 25 is protected.So this PR adds the exclusion locally, with a comment saying it can be dropped once a parent carrying it is released. Any repo in the org converting site docs to Markdown before parent 26 ships needs the same thing, and will otherwise lose pages without a single warning in the build log.
Two related things I noticed but haven't touched, both in
plexus-pomand better as their own change:<excludes><excludes>target/**</excludes></excludes>— the inner element should be<exclude>.plexus-velocitydidn't hit this (Convert the site document from xdoc to Markdown plexus-velocity#101 converted cleanly) because its site build doesn't fork into the default lifecycle, so Spotless never ran. That makes the failure intermittent across repos, which is worse than consistent.Converter defects fixed
doxia-converter1.3 — note 2.0.0 doesn't exist, Central has only 1.0–1.3 — gets three things wrong on xdoc, all invisible in the Markdown:---fences, so Doxia never parses it and title/author are lost.<section>renders<h1>but came out##.It also escaped characters inside inline code spans, where the backslash renders literally:
`\[realm.name\]`,`\*`,`$\{propname\}`. Unescaped.Verified
Built before and after, diffed the normalised pages — title, author metadata, visible text, every link target:
The comparison covers
<head>, not just the body. That matters — a body-only check would have passed the very first build, which had lost everything.The
COMPATIBILITY.md/ Sisu-bytecode paragraph on the index page is preserved verbatim. URLs are unchanged:x.xmlandx.mdboth producex.html.