A template for a typical 'xdoc' can be found in this section of the main Maven site, we'll just discuss a few additions here.
The xdoc plugin will produce
<h3> headings for
<subsection> elements, respectively.
It is therefore perfectly valid to put some sub-headings
<h6>) inside a subsection. For instance,
1.10 on, the
allows for an optional
id attribute in the
<section name="Section" id="Section1"> <subsection name="SubSection" id="SubSection1"> </subsection> </section>
An anchor is constructed from each
id attribute, so you can
reference sections and subsections from other source documents.
Note that each
id attribute has to be unique within one
In previous versions of the plugin, an
id attribute was
constructed from section/subsection names, replacing special
characters by underscores. For backwards compatibility reasons,
we keep this behaviour, i.e., if no
is present, an anchor is constructed from the
Note that this presents two shortcomings:
We recommend that you provide an
id attribute if you want
to reference a section or subsection.
If you need to include the contents of another XML document in your
document, you can use the
as demonstrated below. For instance, the code:
<?xml version="1.0"?> <!DOCTYPE document [ <!ENTITY escapeXmlExample SYSTEM "file:xdocs/escapeXml.xml"> ]> <escapeXml>&escapeXmlExample;</escapeXml>
would produce the following output (click
here to see the content of
<example name="escapeXml"> <text>This is an example of the escapeXml tag usage.</text> </example>
Note that it is possible to validate the included
xml file with the
xdoc:validate goal even if it is not
a valid xdoc document (like in the example above). You just have to
provide a custom
.xsd schema file
with the same base name in the same directory. Otherwise,
you should use the
property to exclude specific files from validation.
You can put a navigation bar on bottom of each page by including a
<navbar/> element in an xdoc's body.
This element takes three optional attributes,
<navbar prev="first.html" home="../index.html" next="next.html"/>
This element should appear after the last
<section/> of the document.
Check the bottom of this page for an example.
Due to a bug in Jelly, it is not possible to use custom entities directly in xdoc documents.
A workaround has been implemented such that you need to embed your entities
<entity> tags. First you should declare the resource file
for your entities:
<?xml version="1.0"?> <!DOCTYPE document [ <!ENTITY % my-entities SYSTEM "entities.ent"> %my-entities; ]> <document> ...
where the file
entities.ent contains, eg:
<!ENTITY version '1.3.2-SNAPSHOT'>
which can then be used in your xdoc like:
<p> This information only applies to version <entity>&version;</entity>. </p>
Note that xdoc files using entities in this way
cannot be validated with the
xdoc:validate goal can be used to check whether your
source files are valid xdoc documents. This should ensure that the
generated html files are valid
To support validation of your xdoc source files by an external tool,
you should include the following
declaration just after the
<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN" "http://maven.apache.org/dtd/xdoc_1_0.dtd">
Here is a list of common mistakes to be aware of:
<p> Here's a list: <ul> <li>item 1</li> <li>item 2</li> </ul> of things to do. </p>
<p> Here's a list: </p> <ul> <li>item 1</li> <li>item 2</li> </ul> <p> of things to do. </p>
Typical block level elements are list elements,
<section name="Downloads"> <a href="downloads.html">Downloads</a> </section>
<section name="Downloads"> <p> <a href="downloads.html">Downloads</a> </p> </section>
Typical inline elements are
<p> The following command executes the program: <source>java -jar CoolApp.jar</source> </p>
<p> The following command executes the program: </p> <source>java -jar CoolApp.jar</source>
However, you may put
<source> elements inside
list items or table rows.