# Xdocs

# Xdoc documents

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.

## Additional sectioning

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,

    <h4>A subsubsection</h4>

will produce:

#### A subsubsection

## Referencing sections and subsections

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

    <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 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:

- If two sections or subsections have identical names (within one source document), you will get an ambiguity when referencing them. Also the resulting html document will not be valid XHTML.
- For long section titles, this leads to rather cumbersome anchor names.

We recommend that you provide an `id` attribute if you want to reference a section or subsection.

## escapeXml Tag

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:

    <?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 `escapeXml.xml`):

    &escapeXmlExample;

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 `.dtd` or `.xsd` schema file with the same base name in the same directory. Otherwise, you should use the `maven.xdoc.validate.exclude` property to exclude specific files from validation.

## Navigation bar

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`:

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

# Validation

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:

## Don't nest block level elements

Wrong:

    <p>
      Here's a list:
      <ul>
        <li>item 1</li>
        <li>item 2</li>
      </ul>
      of things to do.
    </p>

Correct:

    <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, `<table>`, `<source>`, `<div>`, `<p>` and `<pre>`.

## Put inline elements inside block level elements

Wrong:

    <section name="Downloads">
      <a href="downloads.html">Downloads</a>
    </section>

Correct:

    <section name="Downloads">
      <p>
        <a href="downloads.html">Downloads</a>
      </p>
    </section>

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

## Right order of elements in <properties>

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

## Dont put <source> inside paragraphs

Wrong:

    <p>
      The following command executes the program:
      <source>java -jar CoolApp.jar</source>
    </p>

Correct:

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