slachiewicz opened a new pull request, #146:
URL: https://github.com/apache/maven-doxia-converter/pull/146
`doxia-converter` does the mechanical part of turning `src/site/apt` into
`src/site/markdown` well. What it cannot do is warn you about the handful of
differences between the two formats that are **not** mechanical and that damage
a page silently — the converted Markdown looks correct and the rendered page is
missing a heading.
This adds a page collecting the ones worth knowing, all of which came out of
actually converting Maven component sites:
- **Velocity eats ATX headings below level one.** In a `*.md.vm` file, `##`
is a Velocity line comment, so the heading vanishes before Doxia sees the
document — no error, no warning. Covers the three ways out, in order of
preference.
- **APT-escaped references become live.** `$\{project.version\}` is
unescaped by the parser, so a page documenting a default value ends up
rendering something like `[org.apache.maven.model.ReportPlugin@c754401]`.
`${esc.d}` is the fix; a backslash is not, and the page explains why.
- **Encoding.** Without an explicit `-outEncoding UTF-8`, an ASCII source is
autodetected as ISO-8859-1 and an APT escaped space is written as a lone `0xa0`
byte.
- What Markdown genuinely cannot express (table captions, intraword
emphasis), and the APT constructs that render *incorrectly today* and come out
better after conversion — so nobody "fixes" them back.
It also adds `tools/normalize-site-page.py`. Comparing raw before/after HTML
is too noisy to be useful (`<b>`/`<strong>`, attribute order, `<code>`/`<a>`
nesting); the script reduces a generated page to its visible text plus link
targets so a `diff` shows only what a reader would notice. The page documents
the two scripting mistakes that make such a comparison silently vacuous.
**Verified:** `mvn site` builds clean, the new page renders with all eight
section headings intact, and the menu entry resolves.
**One thing to call out:** I put the script at `tools/` because the repo has
no existing home for non-Java tooling. Happy to move it, or to drop it and keep
only the guide, if you would rather not carry a Python file here.
<!-- Generated with assistance from Claude Opus 5; see the Generated-by
trailer on the commit. -->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
