You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/07 20:55:53 UTC
(maven-doxia-site) branch master updated: Add a Markdown format reference
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia-site.git
The following commit(s) were added to refs/heads/master by this push:
new f4a1a14 Add a Markdown format reference
f4a1a14 is described below
commit f4a1a142104a7003cc53506421f920cc9ffc1d2c
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Aug 7 22:52:49 2026 +0200
Add a Markdown format reference
Markdown is the format Maven documentation should use now, and it was the only
supported format without a reference page: the format table pointed at a section
of the modules guide, which describes the module rather than the format.
The page covers what is specific to Doxia rather than restating CommonMark: which
flexmark extensions are enabled, the YAML front matter keys that become the
document title and meta tags, the MACRO comment syntax, what Velocity does to a
*.md.vm page - including reading ## as a line comment inside fenced blocks - and
the handful of things APT could express that Markdown cannot.
Also notes in the format table that Apt predates Doxia's Markdown support, and
links doxia-converter for anyone converting an existing document.
---
content/markdown/references/index.md | 4 +-
content/markdown/references/markdown-format.md | 130 +++++++++++++++++++++++++
content/site.xml | 1 +
3 files changed, 133 insertions(+), 2 deletions(-)
diff --git a/content/markdown/references/index.md b/content/markdown/references/index.md
index 8205aa8..98549cb 100644
--- a/content/markdown/references/index.md
+++ b/content/markdown/references/index.md
@@ -36,11 +36,11 @@ The source directory is the directory under which Maven expects source documents
|Format|Short description|Parser<br />(input)|Sink<br />(output)|Source Directory|File Extension|Doxia Module|Parser Id|
|---|---|---|---|---|---|---|---|
-|[Apt](./apt-format.html)|Almost Plain Text|||`apt`|`apt`|[`doxia-module-apt`](../doxia/doxia-modules/doxia-module-apt/)|`apt`|
+|[Apt](./apt-format.html)|Almost Plain Text, predates Doxia's Markdown support|||`apt`|`apt`|[`doxia-module-apt`](../doxia/doxia-modules/doxia-module-apt/)|`apt`|
|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Converter Doxia Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/converter-module-setup-and-configuration/), only emits `Sink.rawText()`|||`asciidoc`|`adoc`, `asciidoc`|[`asciidoctor-converter-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`|
|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Parser Doxia Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/), still in beta|||`asciidoc`|`adoc`, `asciidoc`|[`asciidoctor-parser-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`|
|[FML](./fml-format.html)|FAQ Markup Language|||`fml`|`fml`|[`doxia-module-fml`](../doxia/doxia-modules/doxia-module-fml/)|`fml`|
-|[Markdown](../modules/index.html#Markdown)|Markdown markup language|||`markdown`|`md`, `markdown`|[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/)|`markdown`|
+|[Markdown](./markdown-format.html)|Markdown markup language|||`markdown`|`md`, `markdown`|[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/)|`markdown`|
|[Xdoc](./xdoc-format.html)|XML Documentation Format|||`xdoc`|`xml`|[`doxia-module-xdoc`](../doxia/doxia-modules/doxia-module-xdoc/)|`xdoc`|
|[XHTML](../modules/index.html#XHTML)|Extensible Hypertext Markup Language|||`xhtml`|`xhtml`|[`doxia-module-xhtml`](../doxia/doxia-modules/doxia-module-xhtml/)|`xhtml`|
diff --git a/content/markdown/references/markdown-format.md b/content/markdown/references/markdown-format.md
new file mode 100644
index 0000000..15b9374
--- /dev/null
+++ b/content/markdown/references/markdown-format.md
@@ -0,0 +1,130 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Markdown Format Reference
+
+Markdown is the format to reach for when writing new Maven documentation. Documents live
+under `src/site/markdown/` and are read by
+[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/), which is included
+with `maven-site-plugin` and needs no extra dependency.
+
+This page covers what is specific to Doxia. For the language itself, read the
+[CommonMark specification](https://commonmark.org/).
+
+## Which Markdown
+
+The module parses with [flexmark](https://github.com/vsch/flexmark-java), configured for
+CommonMark plus these extensions:
+
+| Extension | What it adds |
+|---|---|
+| Tables | GitHub-style pipe tables |
+| Definition lists | `Term` followed by `: definition` |
+| Footnotes | `[^1]` references and definitions |
+| Abbreviations | `*[HTML]: HyperText Markup Language` |
+| Autolink | bare URLs become links |
+| Strikethrough | `~~text~~` |
+| Wiki links | `[[page]]` |
+| Typographic | straight quotes, `...` and `--` become their typographic forms |
+| Escaped character | a backslash escapes the character after it |
+
+The typographic extension is worth knowing about: `"quoted"` renders with curly quotes and
+`...` renders as a single ellipsis character. That is normally what you want in prose, but
+it is a surprise inside a literal string, so put those in a code span.
+
+## Document metadata
+
+A document may open with a YAML front matter block. It must be the very first thing in the
+file — the parser only looks for it when the source begins with `---` — so a licence header
+goes below it, not above.
+
+```markdown
+---
+title: Introduction
+author:
+ - Jane Developer
+ - jane@example.org
+date: 2026-08-07
+---
+```
+
+Recognised keys are `title`, `author`, `date`, `address`, `affiliation`, `copyright`,
+`email`, `keywords`, `language`, `phone` and `subtitle`. The skin turns them into the
+document title and its `meta` tags; each `author` entry becomes its own
+`<meta name="author">`.
+
+Without a `title`, the page's first heading is used instead. That is usually not the same
+text, so a page that means to have a distinct title should say so explicitly.
+
+## Macros
+
+Doxia macros are written as an HTML comment:
+
+```markdown
+<!-- MACRO{toc|fromDepth=1|toDepth=2} -->
+
+<!-- MACRO{snippet|id=example|file=src/main/resources/example.xml} -->
+```
+
+See the [macros reference](../macros/index.html) for the ones that ship with Doxia.
+
+## Velocity
+
+A document named `*.md.vm` is run through Velocity before Doxia parses it, which lets it
+interpolate `${project.version}` and friends.
+
+**Velocity reads `##` as a line comment.** In a `*.md.vm` document every heading below
+level one is deleted before Doxia ever sees the page, and nothing reports it. Three ways
+around it:
+
+- give the page no `.vm` suffix if it does not really need Velocity;
+- use a setext underline for a level two heading, with a blank line before the title:
+
+ ```markdown
+ Goals Overview
+ --------------
+ ```
+
+- wrap a deeper heading, or a whole block, in Velocity's unparsed markup:
+
+ ```markdown
+ #[[### Configuring the plugin]]#
+ ```
+
+ This applies inside fenced code blocks too: Velocity does not know what a code block is,
+ so a sample containing `##` needs the same treatment.
+
+To show a reference rather than resolve it, write `${esc.d}{project.version}`. A backslash
+only works when the reference happens to resolve.
+
+## What Markdown cannot express
+
+If you are converting an existing document, these have no Markdown equivalent:
+
+- a table caption;
+- a second header row part way down a table — it becomes an ordinary row;
+- a table with no header at all: Markdown requires one, so an empty header row appears;
+- `_emphasis_` directly after a word character, which Markdown does not treat as emphasis.
+
+## Converting an existing document
+
+[`doxia-converter`](../doxia-tools/doxia-converter/) converts APT, XDoc and XHTML sources to
+Markdown. Its output is a good first draft rather than a finished page; build the site
+before and after and compare the generated HTML, since the failure modes above are all
+invisible in the converted source.
diff --git a/content/site.xml b/content/site.xml
index 30a11e9..635232a 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -54,6 +54,7 @@ under the License.
<menu name="Documentation">
<item name="Format References" href="references/index.html" collapse="true">
+ <item name="Markdown Format" href="references/markdown-format.html"/>
<item name="Apt Format" href="references/apt-format.html" collapse="true">
<item name="Doxia Apt Enhancements" href="references/doxia-apt.html"/>
</item>