[PR] Document migrating a project's site from APT to Markdown [maven-doxia-converter]

["slachiewicz (via GitHub)" <gi...@apache.org>]

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: issues-unsubscribe@maven.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Document migrating a project's site from APT to Markdown [maven-doxia-converter]

["slachiewicz (via GitHub)" <gi...@apache.org>]

slachiewicz merged PR #146:
URL: https://github.com/apache/maven-doxia-converter/pull/146


-- 
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: issues-unsubscribe@maven.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org