Port the site documentation from APT to Markdown - #227
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.
7 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:48
ee9e79c to
419bf23
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
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