Skip to content

Port the site documentation from APT to Markdown - #1149

Merged
slachiewicz merged 2 commits into
apache:maven-plugin-tools-3.xfrom
slachiewicz:site-apt-to-markdown-3x
Aug 7, 2026
Merged

Port the site documentation from APT to Markdown#1149
slachiewicz merged 2 commits into
apache:maven-plugin-tools-3.xfrom
slachiewicz:site-apt-to-markdown-3x

Conversation

@slachiewicz

Copy link
Copy Markdown
Member

The maven-plugin-tools-3.x maintenance line still carries its site documentation in APT, so a release from it would publish the old pages while the default branch serves Markdown. This brings the two into line.

Two commits: a pure git mv so that git log --follow and git blame still reach each page's history, then the conversion. Please merge or rebase rather than squash — squashing collapses the rename.

Things that needed doing by hand, each found by comparing generated HTML rather than by reading the converted source:

  • Velocity reads ## as a line comment, so in a page that keeps its .vm suffix every heading below level one would be silently deleted. Level two uses a setext underline, deeper ones an unparsed #[[ ]]# block.
  • Where APT wrote $\{foo\} for a reference it means to display, its parser strips the backslashes, so the converted page carried a live reference. Those are now ${esc.d}{foo} — in .vm pages only, since a plain .md is never run through Velocity and ${esc.d} would render literally there.
  • A few things APT renders literally that Markdown reinterprets: a double hyphen (the typographic extension folds it into an en dash), an asterisk mid-line, and an emphasis run that ends in *.

Verified by building the site before and after and comparing all 228 generated pages: every one is identical in its title, author and date metadata, its visible text and every link target.

Kept as its own commit so that git log --follow and git blame still reach each
page's history once the content changes.
The maintenance line still carried its site documentation in APT, so a release from
it would have published the old pages while the default branch serves Markdown.

Velocity reads ## as a line comment, so in a page that keeps its .vm suffix the
level two headings use a setext underline and deeper ones are wrapped in an
unparsed block. Where APT wrote $\{foo\} for a reference it means to display,
the parser strips the backslashes, so those are now ${esc.d}{foo}.

Verified by building the site before and after and comparing all 228 generated
pages: every one is identical in its title, author and date metadata, its visible
text and every link target.
@slachiewicz
slachiewicz merged commit c93f5ce into apache:maven-plugin-tools-3.x Aug 7, 2026
11 checks passed
@github-actions github-actions Bot added this to the 3.16.0 milestone Aug 7, 2026
@slachiewicz
slachiewicz deleted the site-apt-to-markdown-3x branch August 7, 2026 22:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant