A perfectly designed project is meaningless without good documentation to back it up. No matter how well designed, without a path to lead new developers up to your stride you may as well write spaghetti code. Without documentation to explain to users how one goes about using your project it will never gain popularity beyond a small group of people (often the developers themselves... and perhaps their moms). Maven acknowledges this need and builds documentation generation as a cornerstone of a comprehensive software development management process.
Site project setupAlthough any individual project can have its own site, oftentimes it is easier to manage a seperate site project. Our examples will assume a seperate site project, however, note that all of this information can just as easily apply to a project that contains code as well.
The simplest way to bootstrap any Maven development is by running an archetype.
mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \
This will generate a sample Maven site project, which may be built by executing the
| |-- format.apt
| `-- index.apt
| `-- faq.fml
| `-- xdoc.xml
| |-- format.apt
| `-- index.apt
| `-- faq.fml
The items to note in the above structure are the
site.xmlfile and the directories under
xdoc; each representing a document notation type. Finally, the
src/site/frsub directory contain a French language version of the documents, rounding out Maven's commitment to built-in internationalization. You must merely add the French language verion to the site plugin's configuration in the POM.
The Site OutlineThe
site.xmlfile is responsible for the structure of the site as a whole, defining the site's banners, the links (upper right-hand corner by default) and the left-hand side (LHS) menu. Note that links in the menu defined below have similar names to the documents above, yet end with
.html. This is because each of the document markups are converted to HTML by the site plugin, more specifically, by Doxia.
<?xml version="1.0" encoding="ISO-8859-1"?>
<item name="Apache" href="http://www.apache.org/" />
<item name="Maven 1.0" href="http://maven.apache.org/"/>
<item name="Maven 2" href="http://maven.apache.org/maven2/"/>
<menu name="Maven 2.0">
<item name="APT Format" href="format.html"/>
<item name="FAQ" href="faq.html"/>
<item name="Xdoc Example" href="xdoc.html"/>
sitephase can easily generate sites of different languages. All one need do is create a site descriptor file similar to the file above, yet suffix the file name with the language code of your choice. The archetype created a French language version for you,
site_fr.xml. At this point Maven will look for a matching language directory under
src/siteand generate that documentation for an audience of that particular language (usually by a webbrowser's language settings). If no matching language is found the
site.xml's language is the default (presumed to be English).
DoxiaThe heart of the Maven site plugin is the Doxia project, which is a self-contained sub-project of Maven (Doxia). Doxia is responsible for converting your chosen document markup to the html that can be deployed to a website. Doxia also has the ability to convert a document from any supported markup to any other supported markup. It does this with
org.apache.maven.doxia.parser.ParserPlexus role and is responsible for converting the implemented markup into a given sink. A Doxia sink implements the
org.apache.maven.doxia.sink.SinkPlexus role and is any supported output, for example XHTML or PDF. This is important to know if you ever decided to write your own modules for Doxia to support.
APTAPT, or Almost Plain Text, can be considered the default documentation method for Maven projects. It is a simple wiki-like syntax that is easily converted to a Doxia sink. If you built the site generated by
maven-archetype-site, navigate to
target/site/format.htmland you will be treated to a comprehensive guide for using APT. There is no need to reproduce it here.
SnippetsA useful feature of Doxia are snippets. Snippets are macros that are given a file and an id.
The macro will search the file for the comment
START SNIPPET: myIDand ending comment
END SNIPPET: myID. For example, add the following to your POM:
<!-- START SNIPPET: props -->
<!-- END SNIPPET: props -->
And the following to your
sitephase, and be amazed! Rather than "file", the snippet can also take a "url".
Hint: rather than running the
sitephase, try running the
site:rungoal. It will launch your documents under a web container accessible from port 8080 that will show your changes in real time.
FMLFML is FAQ Markup Language, and is specialized in creation the ubiquitous Frequently Asked Questions (FAQ) document. An example is as follows:
<question>What is a good question?</question>
<p>Any valid XHTML can be placed in the <code>answer</code> element</p>
The FML document can have any number of parts, and each part may have any number of FAQs - each having one question and one answer. When the document is generated, it will place all questions at the top of the page as links, which anchor to the answer later in the page.
XDocXDoc is an XML markup for writing documents, and has been around since the early days of Maven 1 and Ant. It is similar to HTML, but document-centric with extra elements for sections and more constraints. All XDoc documents must be under the xdoc directory, with a
.xmlextension. Its support is mostly for historical reasons, and it is recommended to write new documentation in APT format.
Look and Feel
Changing SkinsChanging skins in Maven is easy. Just alter your POM, and viola! Your entire site's look and feel has been altered. Better yet, it is all consistent. To switch the
my-siteproject to use the Stylus theme, alter the
The list of default skins available from Maven Central Repository are here http://repo1.maven.org/maven2/org/apache/maven/skins/. At the time of this article's writing, the list is:
As you probably guessed,
maven-default-skinis the default.
Creating your own skinFirst, create a project with the following layout:
| `-- maven-theme.css
and a simple
The important file in a custom skin is the
maven-theme.css. Also note the
src/main/resource/imagesdirectory that allows you to add images into your CSS, accessible as "/images/my-image.ext". Most control of the css is via the basics like
a, but there are a few important CSS
ids generated by default
- breadcrumbs - a sequence of data at the top of the page
- leftColumn - represents the left column of the page
- navcolumn - wraps the navigation elements in the left column
- banner - contains the left and right banners defined in the site.xml
- bodyColumn - wraps the contentBox of the page
- contentBox - contains the main content of the page
- footer - contains the data generated as a page footer
Velocity ManipulationSkin manipulation is nice to change the look of your site, but in order to change the way the site is generated requires creating your own Velocity (
.vm) file. Apache Velocity is a templating engine that has been around for years, has proven its metal in projects such as Apache Turbine, and is a simple method for allowing users to overwrite the default templates.
Rather than starting from scratch, it is far simpler to download the default
default-site.vmfile and manipulate it. The default renderer is available under the doxia-site-rendered project source code, available for download under the doxia project. Doxia is available from the subversion repository http://svn.apache.org/repos/asf/maven/doxia/trunk/
(if not found there, check the doxia website at http://maven.apache.org/doxia). From there, the doxia-site renderer project's resource contains the template, at
doxia-site-renderer/src/main/resources/org/apache/maven/doxia/siterenderer/resources/default-site.vm. Copy this file to your project at
src/site/my-site.vm, and point your
pom.xmlto utilize it.
If you look at the my-site.vm, you will notice the XHTML and CSS generated by it. This gives you the power to alter the structure of your generated Maven site, as well as allow your custom skins more control than merely the default (perhaps by adding more spans, or more types of CSS classes).
Or, better yet, you can add the template to your skin, to
src/main/resources/META-INF/maven/site.vm. This way, when a project uses your skin, they automatically use your template.
DistributionThe final step in site generation is publishing it to a location where a public webserver may access it. There is a special element in the
site, which gives the location and method of distribution. In your
my-sitePOM, you will notice the element has been added for you. Now you merely need to set it like any other Maven distribution. The example uses secure copy protocol (scp).
With a suitable distribution set up, you merely run the
site-deployphase (which has bound to it the
That's it! Maven will generate the documentation using your chosen template and skin, and copy those files to the specified location.