]> Xdocs

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 <h2> and <h3> headings for <section> and <subsection> elements, respectively. It is therefore perfectly valid to put some sub-headings (<h4>, <h5>, <h6>) inside a subsection. For instance,

A subsubsection]]>

will produce:

A subsubsection

From version 1.10 on, the xdoc plugin allows for an optional id attribute in the section and subsection elements:

]]>

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 source document.

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 id attribute is present, an anchor is constructed from the name attribute. 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 <escapeXml> tag, as demonstrated below. For instance, the code:

]> &escapeXmlExample;]]>

would produce the following output (click here to see the content of escapeXml.xml):

&escapeXmlExample;

Note that currently it is not possible to validate arbitrary xml files with the xdoc:validate goal. You can use the maven.xdoc.validate.exclude 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, prev, home and next:

]]>

This element should appear after the last <section/> of the document. Check the bottom of this page for an example.

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 XHTML1-transitional. Here is a list of common mistakes to be aware of:

Wrong:

Here's a list:
  • item 1
  • item 2
of things to do.

]]>

Correct:

Here's a list:

  • item 1
  • item 2

of things to do.

]]>

Typical block level elements are list elements, <table>, <source>, <div>, <p> and <pre>.

Wrong:

Downloads
]]>

Correct:

Downloads

]]>

Typical inline elements are <a>, <strong>, <code>, <font>, <br> and <img>.

The <title> element has to come before <author>.