Doxia Markup Languages References
The following table gives an overview of the markup languages currently supported by Doxia:
-
if a Parser is available for a given format, it means that you can write your documentation in this language and Doxia can generate output from it,
-
if a Sink is available, it means you can generate output in this format.
The source directory is the directory under which Maven expects source documents in this format (e.g. src/site/apt/ for Apt), the file extension is the default file extension, and the parser id is the unique identifier used to look up the corresponding component.
| Format | Short description | Parser (input) |
Sink (output) |
Source Directory | File Extension | Doxia Module | Parser Id |
|---|---|---|---|---|---|---|---|
| Apt | Almost Plain Text, predates Doxia's Markdown support | apt |
apt |
doxia-module-apt |
apt | ||
| AsciiDoc | Asciidoctor Converter Doxia Module, only emits Sink.rawText() |
asciidoc |
adoc, asciidoc |
asciidoctor-converter-doxia-module |
asciidoc | ||
| AsciiDoc | Asciidoctor Parser Doxia Module, still in beta | asciidoc |
adoc, asciidoc |
asciidoctor-parser-doxia-module |
asciidoc | ||
| FML | FAQ Markup Language, deprecated since Doxia 2.2.0 | fml |
fml |
doxia-module-fml |
fml | ||
| Markdown | Markdown markup language | markdown |
md, markdown |
doxia-module-markdown |
markdown | ||
| Xdoc | XML Documentation Format | xdoc |
xml |
doxia-module-xdoc |
xdoc | ||
| XHTML5 | Extensible Hypertext Markup Language, HTML5 serialisation | xhtml |
xhtml |
doxia-module-xhtml5 |
xhtml |
Note some modules are not included per default with the site plugin. Have a look at the available modules here: https://repo.maven.apache.org/maven2/org/apache/maven/doxia/.
If you need to add a module that is not bundled, for example AsciiDoc, add it as a dependency of the plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>...</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-parser-doxia-module</artifactId>
<version>3.2.0</version>
</dependency>
</dependencies>
</plugin>
Limitations
Every format is converted through the Doxia Sink API. A markup feature that the API cannot express, or that the target format has no syntax for, is dropped or approximated in the output. The following sections list what an author sees per format. A feature that is not listed is written as expected.
Markdown sink
The Markdown sink writes CommonMark with GitHub-style tables. For the cases that Markdown cannot express at all, such as a table caption or a table without a header row, see What Markdown cannot express. The sink handles the following features as shown.
| Feature | Output |
|---|---|
| Anchor | An empty <a id="name"></a> element in front of the text, because Markdown has no anchor syntax. The text that follows is not wrapped. A name that is not a valid id is encoded, so my anchor becomes my_anchor, and links to it get the same encoding. |
| Figure | . The caption becomes the alternative text, and the alt, title, width and id attributes are dropped. A standalone image keeps its alt text but loses title and width. |
| Table alignment | Written once, in the delimiter row after the first row, from the column alignment or from the alignment of the first-row cells. Alignment on later rows is ignored. A column without alignment inherits the one before it. |
| Table cell spans and grid | colspan, rowspan and the grid flag are dropped, so a spanning cell occupies one column. |
| Numbered list style | Always decimal. Other styles, such as roman numerals, are replaced with a warning. |
| Definition list | Raw HTML <dl>, <dt> and <dd> elements, with a warning. |
| Inline styles | Code, emphasis, strong and strikethrough use Markdown syntax. Others, such as subscript, superscript and small, are written as raw HTML elements. |
| Elements without a Sink event | Raw HTML, for example <div>, <wbr />, <time> and <data>. |
| Page break | Ignored, with a warning. |
| Source block language | A source block opens with the info string unknown, because the language is not carried over. |
| Link inside a code block | Dropped, with a warning. |
id, class, style and other attributes |
Dropped on headings, paragraphs, lists, tables and links. |
APT sink
| Feature | Output |
|---|---|
| Anchor | The anchor name is ignored. The anchored text becomes the name, written as {text}. |
| Inline styles | Only italic, bold and monospaced are written. Others, such as strikethrough and subscript, keep their text and lose the markup. |
| Table alignment | Taken from the column alignment only. Cell alignment attributes are ignored, and columns without alignment are centered. |
| Table caption | Written as plain text after the table. |
| Table cell spans | Not written. |
| Line break in a table cell | Splits the table row. |
| Figure | [src] caption on one line. The figure attributes are dropped. |
| Block quote, division, article, header, footer, navigation, time and data | No markup. The text content is kept. |
| Section title deeper than level 5 | Written as level 5, with a warning. |
| Elements without a Sink event | Dropped, with a warning. |
XDoc sink
| Feature | Output |
|---|---|
| Section titles at level 3 to 6 | XDoc has only section and subsection elements. Deeper titles are written as <h3> to <h6> headings without an enclosing element. |
| Page break | An XML comment, <!-- PB -->. |
XHTML5 sink
| Feature | Output |
|---|---|
| Page break | An HTML comment, <!-- PB -->. |
| Anchor | A name that is not a valid id is encoded, so my anchor becomes my_anchor. |
| Elements without a Sink event and without a known HTML tag | Dropped, with a warning. |
Parsers
The following parser behavior is visible in the output of other formats.
- Markdown: task list syntax is not recognized.
- [ ] taskstays a list item with the literal text[ ] task. - Markdown: a footnote becomes an item of a numbered list at the end of the document, with a back link.
- Markdown: front matter keys other than
title,authoranddate, such askeywordsorsubtitle, reach the sink asmetaelements without a Sink event. The APT sink drops them. - Markdown: table alignment is passed on cell by cell, not as column alignment, so the APT sink does not write it.
- XHTML5, XDoc and FML: an element that is not recognized is passed to the sink as an element without a Sink event, with a warning. What survives depends on the sink, as in the tables above.
- FML has a parser but no sink.
Former Doxia Formats
The following table gives an overview of the formats which used to be supported mostly as Parser in former versions of Doxia:
| Format | Short description | Doxia Module | Removed Since |
|---|---|---|---|
| iText | iText PDF Library | doxia-module-itext |
2.0 |
| FO | XSL formatting objects (XSL-FO) | doxia-module-fo |
2.0 |
| LaTeX | LaTeX typesetting system | doxia-module-latex |
2.0 |
| RTF | Microsoft Rich Text Format | doxia-module-rtf |
2.0 |
| Confluence | Confluence Enterprise Wiki | doxia-module-confluence |
2.0 |
| Simplified DocBook | Simplified DocBook XML Standard | doxia-module-docbook-simple |
2.0 |
| TWiki | TWiki Structured Wiki | doxia-module-twiki |
2.0 |
| XHTML | XHTML 1.0, superseded by the XHTML5 module | doxia-module-xhtml |
2.0 |

