Additional site content
documents go in src/site/xxx
, where
xxx
is the file format.
For example APT documents live under
src/site/apt
.
images and other resources go in src/site/resources and are referenced relative to this directory.
For example images typically live under
src/site/resources/images
.
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.
Maven sites can include documentation in any of a number of file formats:
Table 8.1. File formats supported by Maven site
Format | Type | Location | Reference |
---|---|---|---|
APT | Wiki-like format | src/site/apt/xxx.apt | Maven Doxia site (APT reference) |
DocBook | Full power of DocBook | src/site/docbook/xxx.xml | DocBook site (quick ref) |
FML | FAQ Markup Language | src/site/fml/xxx.xml | Maven Doxia site (FML reference) |
XDoc | Simplified DocBook, used in Maven 1. | src/site/xdoc/xxx.xml | Maven 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”.
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.
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
In addition to regular font, we can specify italics, bold or monospaced:
<italicised text> <<bold text>> <<<monospaced text>>>
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
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
To quote a code block, use 3 dashes (---
)
before and after:
---------------------------------------- public class FooBar { ... } ----------------------------------------
To put into a box, use a plus symbol
(+--
)
In addition to the above, APT supports tables, horizontal rules (===), page breaks, comments and special characters. See the Maven Doxia site for further details.