slachiewicz opened a new pull request, #1633: URL: https://github.com/apache/maven-site/pull/1633
Sits on top of #1632 — the first two commits here are that PR, since the plugin documentation guide has to be Markdown before its content can be rewritten. **Review the last commit only**; once #1632 merges this will rebase down to two files. Two pieces of normative guidance still point new documentation at APT: **`guides/mini/guide-site.md`** lists `apt` first and calls it the format "like this one" — which stopped being true when that guide itself became Markdown. It now lists `markdown` first, says plainly that new documentation should use it, and describes APT as a format that predates Maven's Markdown support: still supported, but the Maven project has moved its own documentation off it. Adds a pointer to `doxia-converter` for anyone converting an existing page. **`guides/development/guide-plugin-documentation`** is the canonical instruction for documenting a plugin, and it gave a full APT template for `src/site/apt/index.apt` — so an author following it started in APT. It now shows the same page as `src/site/markdown/index.md`, with the YAML front matter that carries the title, author and date, plus a note about naming the file `index.md.vm` and keeping headings away from `##` if the page needs Velocity. One thing worth seeing: that guide is itself a Velocity template, and Velocity reads `##` as a line comment **even inside a fenced code block**. The first version of this change silently lost `## Goals Overview` and `## Usage` from the rendered sample. It is now wrapped in `#[[ ]]#`. That only showed up because the built page was checked rather than the source. Verified by building the site: the sample renders all its headings and no `#[[` markup leaks into the page. -- 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]
