slachiewicz opened a new pull request, #247: URL: https://github.com/apache/maven-reporting-impl/pull/247
Back-ports to the live `maven-reporting-impl-3.x` line the APT-to-Markdown conversion already merged on master. Base branch: **`maven-reporting-impl-3.x`**, not `master`. ### Mirrors the master-side conversion | this PR | master | | --- | --- | | Rename the site document ahead of converting it | [`bcd47ea`](https://github.com/apache/maven-reporting-impl/commit/bcd47ea995e7b29c997700c7ec96c9fde9fd7aa3) | | Port the site documentation from APT to Markdown | [`d4c4f6b`](https://github.com/apache/maven-reporting-impl/commit/d4c4f6b6f98c3a291b9ba3f65206fd5c758436a0) | The page's prose has diverged between the two lines (master picked up MSHARED-1314 and the release/Doxia history table), so the content commit does not cherry-pick. It is converted by hand to the same shape: `<<<code>>` becomes backticks, `<<bold>>` becomes `**bold**`, `{{{url}text}}` becomes `[text](url)`, and the per-line `~~` licence header becomes a single block HTML comment. The rename is a separate commit so `git log --follow` and `git blame` still reach the page's history — please **merge or rebase, not squash**. ### Two deliberate differences from master, both forced by this branch's toolchain This branch inherits maven-shared-components 34, so the site is rendered by maven-site-plugin 3.7.1 / Doxia Site Renderer 1.8.1 — the `<doxiaVersion>1.12.0</doxiaVersion>` property is the component's own compile dependency, not what builds its site. 1. **The document metadata is a MultiMarkdown block, not YAML front matter.** `doxia-module-markdown` 1.8 matches `key: value` lines terminated by a blank line and knows nothing about `---` fences. I tried master's fenced form here first: the fences and the keys are rendered into the page as visible text, and `<title>` falls back to the first heading while the `author` and `date` meta tags disappear entirely. The unfenced form is also what 1.11.1, 1.12.0 and 2.0.0 match, so it keeps working if this branch's site plugin is ever bumped; the `---` fences only start being understood at 1.12.0. 2. **The page is a plain `.md`, not `.md.vm`.** Master's copy interpolates `${project.scm.tag}`; this branch's only ever used `${project.name}`, so the title is spelled out and Velocity drops out — which also removes any chance of a `##` heading being swallowed as a Velocity line comment. ### Verification `mvn site` before and after on this branch, both green, all 16 generated pages compared. The `<title>`, `<meta name="author">` and `<meta name="date">` tags, the visible text and every link target are identical, and every section keeps its anchor (`#Usage`, `#History`, `#Doxia_runtime`, `#Doxia_dependency`, `#Upgrading_to_maven-reporting-impl_2.3.2B`). `mvn apache-rat:check` passes. Two rendered differences remain, both from `doxia-module-markdown` 1.8 emitting flexmark's HTML instead of driving Doxia's section sink: * headings move up one level — the page title is now an `<h1>` where APT gave an `<h2>`, and sections follow. The page title no longer carries an anchor of its own; nothing in the generated site links to `#Apache_Maven_Reporting_Implementation`. * the "edit this page" link points at the new path. If you would rather the two lines match master byte for byte on the metadata, the alternative is bumping maven-site-plugin on this branch to a 1.12.0-or-later Doxia — a build change I did not want to fold into a documentation PR. `src/site/xdoc/download.xml.vm` is deliberately untouched. <sub>Drafted with Claude — please verify</sub> -- 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]
