Port the site documentation from APT to Markdown - #572
Merged
slachiewicz merged 2 commits intoAug 6, 2026
Conversation
slachiewicz
force-pushed
the
site-apt-to-markdown
branch
from
August 6, 2026 00:33
2e7dbe7 to
a78fc3f
Compare
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.
5 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
#[[ ... ]]#
- references APT rendered literally are escaped, so they do not resolve
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 in prose picking up the
Markdown module's typographic substitution.
slachiewicz
force-pushed
the
site-apt-to-markdown
branch
from
August 6, 2026 12:47
a78fc3f to
ac2abe6
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 5 page(s) 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