Site documentation across the Maven repositories was largely written in APT, a format only Doxia understands and few contributors can edit comfortably. Markdown is supported by maven-site-plugin out of the box, and doxia-converter can do most of the mechanical work.
This issue tracked the migration, the tooling fixes it turned up, and the repair of pages an earlier conversion damaged. The bulk of the work is done and the rest is in review, so it is being closed; the open pull requests below will be merged on their own.
What was done
|
|
| Site APT documents at the start |
729 |
| Ported, in 66 pull requests across 47 repositories |
63 merged, 3 still open |
| Follow-up pull requests |
46 restoring document metadata, 22 tidying escapes |
| APT pages left |
388, mostly surefire, the Maven 3 line and second checkouts |
Every port was verified by building the site before and after the change and comparing the visible text and every link target of every generated page.
Each pull request is two commits: a pure git mv, so git log --follow and git blame still reach a page's history, and then the conversion. Please merge or rebase rather than squash — squashing collapses the rename and the history is lost again.
Two things the first pass got wrong
Document metadata was dropped. An APT document opens with a header block giving its title, authors and date; doxia-converter turns that into YAML front matter, and the port script removed it along with the converter's per-line licence comments. 387 pages across 47 repositories lost their author and date meta tags, and took their <title> from the first heading instead of from the document title — so Release Notes – Modello became Modello – Modello. The front matter has to be the first thing in the file, because the Markdown parser only looks for it when the source begins with ---; RAT is happy with the licence header below it.
That slipped through because the verification normalised each page to its visible text and link targets, which ignores <head> entirely.
Older conversions over-escaped. Pages converted years ago carry a backslash in front of punctuation that is not markup where it stands — maven\-source\-plugin, \(default\), required\.. Around 1,200 of them across 115 pages. Angle brackets, a full stop after a digit and runs of dots keep their escapes; the rest are gone.
Tooling fixes
What the conversion has to get right
Each of these was found by comparing generated HTML, not by reading the converted source.
## is a Velocity line comment. In a *.md.vm page every heading below level one is deleted before Doxia sees it, with no error. Drop the .vm where the page only used it for ${project.name}; otherwise use a setext underline for level two and #[[### … ]]# deeper.- A reference the page means to show. Write
${esc.d}{foo}; a backslash only works when the reference happens to resolve.
- Constructs Markdown cannot express. Table captions are lost, a second header row part way down a table becomes an ordinary row, and
_x_ after a word character is not emphasis.
- Tests that read the documentation.
ArtifactHandlerTest and DefaultTypeProviderTest in apache/maven parse a site table to check it against the code, so they move with the page.
Some differences are repairs rather than regressions: an anchor containing a space never resolved, and APT invented anchors out of ${...} braces.
Pages that still carry Velocity
338 pages remain *.md.vm. Most are templates only so that ${project.version} stays current inside a <version> element of an example POM; dropping that element would make them plain Markdown. The full breakdown, with a link to every page, is in the comment below.
Not converted
src/test and src/it fixtures, which are inputs to Doxia's own tests, and src/main/resources/archetype-resources, which is template content for users' generated projects.
Site documentation across the Maven repositories was largely written in APT, a format only Doxia understands and few contributors can edit comfortably. Markdown is supported by
maven-site-pluginout of the box, anddoxia-convertercan do most of the mechanical work.This issue tracked the migration, the tooling fixes it turned up, and the repair of pages an earlier conversion damaged. The bulk of the work is done and the rest is in review, so it is being closed; the open pull requests below will be merged on their own.
What was done
Every port was verified by building the site before and after the change and comparing the visible text and every link target of every generated page.
Each pull request is two commits: a pure
git mv, sogit log --followandgit blamestill reach a page's history, and then the conversion. Please merge or rebase rather than squash — squashing collapses the rename and the history is lost again.Two things the first pass got wrong
Document metadata was dropped. An APT document opens with a header block giving its title, authors and date;
doxia-converterturns that into YAML front matter, and the port script removed it along with the converter's per-line licence comments. 387 pages across 47 repositories lost their author and date meta tags, and took their<title>from the first heading instead of from the document title — soRelease Notes – ModellobecameModello – Modello. The front matter has to be the first thing in the file, because the Markdown parser only looks for it when the source begins with---; RAT is happy with the licence header below it.That slipped through because the verification normalised each page to its visible text and link targets, which ignores
<head>entirely.Older conversions over-escaped. Pages converted years ago carry a backslash in front of punctuation that is not markup where it stands —
maven\-source\-plugin,\(default\),required\.. Around 1,200 of them across 115 pages. Angle brackets, a full stop after a digit and runs of dots keep their escapes; the rest are gone.Tooling fixes
*.vmsourceWhat the conversion has to get right
Each of these was found by comparing generated HTML, not by reading the converted source.
##is a Velocity line comment. In a*.md.vmpage every heading below level one is deleted before Doxia sees it, with no error. Drop the.vmwhere the page only used it for${project.name}; otherwise use a setext underline for level two and#[[### … ]]#deeper.${esc.d}{foo}; a backslash only works when the reference happens to resolve._x_after a word character is not emphasis.ArtifactHandlerTestandDefaultTypeProviderTestin apache/maven parse a site table to check it against the code, so they move with the page.Some differences are repairs rather than regressions: an anchor containing a space never resolved, and APT invented anchors out of
${...}braces.Pages that still carry Velocity
338 pages remain
*.md.vm. Most are templates only so that${project.version}stays current inside a<version>element of an example POM; dropping that element would make them plain Markdown. The full breakdown, with a link to every page, is in the comment below.Not converted
src/testandsrc/itfixtures, which are inputs to Doxia's own tests, andsrc/main/resources/archetype-resources, which is template content for users' generated projects.