slachiewicz opened a new pull request, #69: URL: https://github.com/apache/maven-doxia-site/pull/69
Markdown is the format Maven documentation should use now, and it was the only supported format without a reference page. The format table on [Format References](https://maven.apache.org/doxia/references/) pointed `Markdown` at a section of the modules guide, which describes the *module* rather than the *format*, while Apt, FML and XDoc each have a full page. The new page covers what is specific to Doxia rather than restating CommonMark: * which flexmark extensions are enabled — tables, definition lists, footnotes, abbreviations, autolink, strikethrough, wiki links, typographic, escaped character — and the surprise that the typographic one turns `"..."` into curly quotes and a single ellipsis character; * the YAML front matter keys that become the document title and its `meta` tags, and the rule that the block has to be the first thing in the file, so a licence header goes below it; * the `<!-- MACRO{...} -->` comment syntax; * what Velocity does to a `*.md.vm` page — in particular that it reads `##` as a line comment and silently deletes every heading below level one, **including inside fenced code blocks** — and the three ways round it; * the handful of things APT could express that Markdown cannot: table captions, a second header row, a table with no header, and `_emphasis_` after a word character. It also notes in the format table that Apt predates Doxia's Markdown support, and links `doxia-converter` for anyone converting an existing document. Verified by building the site: the page renders with all its headings, no Velocity markup leaks, and the new navigation entry appears under Format References. -- 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]
