Port the site documentation from APT to Markdown - #433
Merged
Conversation
A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. Mirrors apache/maven 6a1b3e39c2, which renamed the same five pages under its/ on master before the tree was moved out of this repository. Generated-by: Claude Opus 5 (1M context)
Back-port of the conversion already merged on apache/maven master, where these
same five pages live under its/: apache/maven d4b5e85010 as amended by
096d59ec94, which restored the YAML front matter that first commit had dropped.
The APT sources here are byte-identical to the ones converted there, so the
Markdown is taken over unchanged and the two lines stay in step.
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- the APT document header becomes YAML front matter, which has to be the first
bytes of the file for the parser to see it; it carries the title, author and
date that the generated page turns into <title> and <meta> tags
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
apache/maven could not build the four modules under its/, so the five pages
were merged there converted but unverified. They are verified here: the site of
each of the four modules was built before and after, and the title, author and
date metadata, the visible text and every link target are unchanged.
Generated-by: Claude Opus 5 (1M context)
slachiewicz
added
documentation
slachiewicz
marked this pull request as ready for review
August 10, 2026 00:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Back-ports to the live
maven-3.10.xline the APT-to-Markdown conversion that is already merged onapache/mavenmaster, where these same five pages live underits/.Base branch:
maven-3.10.x(notmaster—masterin this repository is an empty stub since "Branch 3.10.x created", and the IT tree now lives inapache/maven).Mirrors the master-side conversion
6a1b3e39c2d4b5e85010as amended by096d59ec94The five APT sources here are byte-identical to the ones converted on master, so the Markdown is taken over unchanged and the two lines stay in step. Master's fix-up commit (which restored the YAML front matter the port had dropped) is folded into the port commit here rather than replayed as a mistake and its repair.
src/site/apt/index.aptsrc/site/markdown/index.mdcore-it-suite/src/site/apt/index.apt.vmcore-it-suite/src/site/markdown/index.md.vmcore-it-suite/src/site/apt/bootstrap.apt.vmcore-it-suite/src/site/markdown/bootstrap.md.vmcore-it-support/core-it-plugins/src/site/apt/index.apt.vm.../markdown/index.md.vmcore-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/apt/index.apt.vm.../markdown/index.md.vmThe rename is a separate commit so git records it and
git log --followandgit blamestill reach each page's history — please merge or rebase, not squash.Verification
apache/mavencould not build the four modules underits/, so its commit message records those five pages as converted but unverified. They are verified here, where the modules do build:mvn -N sitein each of the four modules that carry a page (.,core-it-suite,core-it-support/core-it-plugins,core-it-support/core-it-plugins/maven-it-plugin-core-stubs), on a pristinemaven-3.10.xworktree and on this branch, with identical flags. Both green.<title>,<meta name="author">and<meta name="date">tags, the visible text and every link target are identical..md.vmpages keep their.vmsuffix and use setext underlines for level two and#[[### ... ]]#for level three, so Velocity cannot swallow a heading as a##comment. Checked in the output:Running Core ITs Suite,Core ITs Suite Results,Core ITs Suite and Dependencies (incl. Plugins)andUsing Local Repository Managerall render, with their anchors unchanged — including#Core_ITs_Suite_and_Dependencies_.28incl._Plugins.29, whichbootstraplinks to.The only changes in the HTML are cosmetic: the licence header now appears once as an HTML comment in the body instead of being stripped, and fenced blocks gain
class="language-shell".Two things I did not verify or touch:
mvn sitefails on this branch, before and after, inmaven-it-plugin-ant-based—maven-enforcer-pluginbansplexus-container-defaultpulled in transitively bymaven-script-ant:2.0.6. Pre-existing and unrelated; that is why the site was built per module.core-it-suite/src/site/markdown/index.md.vmcarriesgithub.com/apache/maven-integration-testing/blob/master/...links inherited verbatim from the APT. Some of them no longer resolve now thatmasteris an empty stub. Left alone to keep this a pure format conversion — worth a follow-up.Drafted with Claude — please verify