Doxia Issues & Gotchas
This page collects behavior that tends to surprise authors and plugin developers. See also the Frequently Asked Questions and the limitations of each format.
Apt anchors and links
In APT, a link to another document must start with ./ or ../. Without it, Doxia treats the target as an anchor in the same page, and an internal link must not start with #. Read the anchors and links sections of the APT reference.
Doxia does not warn about a link that lacks the prefix. It turns the link into an anchor in the same page, so {{{doxia-apt.html}text}} becomes <a href="#doxia-apt.html"> and {{{references/doxia-apt.html}text}} becomes <a href="#references.2Fdoxia-apt.html">. Both are broken in the output and Doxia does not warn, so check the links in the generated pages, or run a link checker over target/site.
Converting the page to Markdown avoids the problem, since Markdown links work as written.
Figure sink events
Doxia distinguishes between figures, which are block-level elements, and images, which are inline. A figure is written as a sequence of events:
sink.figure();
sink.figureGraphics("figure.png");
sink.figureCaption();
sink.text("Figure caption");
sink.figureCaption_();
sink.figure_();
The HTML5 sink writes this as:
<figure><img src="figure.png" /><figcaption>Figure caption</figcaption></figure>
A figureGraphics(...) event on its own, outside figure(), writes just the inline <img> element. Pass the alternative text as the alt attribute in a SinkEventAttributeSet; a caption is not used as alternative text.
Empty Generated Page
If a report page comes out empty after mvn site, check that the report closes its sink with sink.close(). Reports that extend AbstractMavenReport from Maven Reporting Implementation get this for free, including the sub-page sinks created through the SinkFactory passed to generate(). A report that implements MavenReport directly, or that creates sinks of its own, must close each of them.

