Port the site documentation from APT to Markdown - #1006
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.
22 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- 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
#[[ ... ]]#
Verified by building the site before and after and comparing every generated
page: the visible text and the link targets are unchanged apart from
<b>/<i> becoming <strong>/<em> and quotes and ellipses in prose picking up
the Markdown module's typographic substitution.
The one remaining difference is a fix: the plugin specification page wrote
<<<${target.groupId}>>>, and APT parsed the braces as an anchor definition,
so the old page rendered "$target.groupId" with the braces swallowed. The
Markdown page renders the literal ${target.groupId} that was meant.
slachiewicz
force-pushed
the
site-apt-to-markdown
branch
from
August 6, 2026 12:49
46a3575 to
2a3d9df
Compare
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.
Converts the 22 pages under
src/site/aptto Markdown. APT is a format onlyDoxia understands; Markdown is already supported by
maven-site-pluginout ofthe box, so no POM change is needed.
The pages were converted with
doxia-converterand then cleaned up by hand:<<<code>>>becomes backticks,<<bold>>becomes**bold**, and{{{url}text}}becomes[text](url)${project.name}is now a plain.mdwith the title spelled out.vm. Velocity reads##as a linecomment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#${esc.d}{...}Verified by building the site before and after the change and comparing every
generated page. The visible text and the link targets are unchanged, apart
from
<b>/<i>rendering as<strong>/<em>and quotes and ellipses inprose picking up the Markdown module's typographic substitution.
Part of the wider migration tracked in
apache/maven-doxia-converter#139