8.4. Writing Additional Site Content

Additional site content

As mentioned above, any document that corresponds to index.html (for example src/site/apt/index.apt) need not be explicitly linked to because it will be the default for the site.

8.4.1. File Formats

Maven sites can include documentation in any of a number of file formats:

Table 8.1. File formats supported by Maven site

FormatTypeLocationReference
APTWiki-like formatsrc/site/apt/xxx.aptMaven Doxia site (APT reference)
DocBookFull power of DocBooksrc/site/docbook/xxx.xmlDocBook site (quick ref)
FMLFAQ Markup Languagesrc/site/fml/xxx.xmlMaven Doxia site (FML reference)
XDocSimplified DocBook, used in Maven 1.src/site/xdoc/xxx.xmlMaven Doxia site (XDoc reference)

Of these, APT is the lowest entry, and is the generally recommended format; see Section 8.4.2, “APT Quick Start”.

8.4.2. APT Quick Start

APT reference is available online at http://maven.apache.org/doxia/references/apt-format.html, but the following are some of the main formatting tips.

8.4.2.1. Sections and Sub-sections

Sections are not indented, paragraphs are.

My section title (not indented).

  My paragraph first line (indented by 2 spaces).  There is no need for remaining 
sentences in the paragraph to be indented.  A blank line terminates the paragraph.

Subsections can be defined using leading asterisks (*) to indicate the subsection level indents:

Section title

* Sub-section title

** Sub-sub-section title

*** Sub-sub-sub-section title

8.4.2.2. Fonts

In addition to regular font, we can specify italics, bold or monospaced:

  <italicised text>
  <<bold text>>
  <<<monospaced text>>>

8.4.2.3. Lists

List items are indented, and begin with an asterisk (*)

  * List item 1.

  * List item 2.

    Paragraph contained in list item 2.

    * Sub-list item 1.

    * Sub-list item 2.

  * List item 3.

To force the end of a list, use the [] pseudo-element:

  * List item 3.
 
  []

  This text is not in the list

8.4.2.4. Links and Figures

To create a hyperlink, use:

  Link to {{http://www.pixware.fr}}.
  or 
  Link to {{{http://www.pixware.fr}Pixware home page}}.

To create an anchor, use:

  {Anchor}. This text is anchored.
  and then
  Link to {{anchor}}.
  or
  Link to {{{anchor}showing alternate text}}

Figures are specified by

  [images/foo/bar.png] Figure caption

8.4.2.5. Code Blocks (verbatim text)

To quote a code block, use 3 dashes (---) before and after:

----------------------------------------
public class FooBar {
  ...
}
----------------------------------------

To put into a box, use a plus symbol (+--)

8.4.2.6. Other Code Elements

In addition to the above, APT supports tables, horizontal rules (===), page breaks, comments and special characters. See the Maven Doxia site for further details.