Maven - (Web)Site (Documentation) Phase

Maven - (Web)Site (Documentation) Phase

About

The site phase generates site documentation.

You can look at the documentation generated under target/site.

Articles Related

Architecture (Doxia)

Doxia is a content generation framework that supports generation of markup languages. Doxia powers the entire documentation system of Maven.

Doxia supports several Markup Language Reference. The first three are recognized by default by the site plugin.

APT: The APT format (“Almost Plain Text”)
FML: The FML format is the FAQ format.
XDoc: The XDoc format is the same as used in Maven 1.x. A reference for the XDoc Format is available.
Maven - Markdown
….

through severals modules:

Configuration

Pom

reporting

Maven has several project reports that you can add to the web site generated.

You define them through Plugin in the Reporting element of the pom.xml.

<project>

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-project-info-reports-plugin</artifactId>
          <version>2.7</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.7</version>
      </plugin>
      ...
    </plugins>
  </build>
  ...
  <!-- To use the report goals in your POM or parent POM -->
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.7</version>
        <reportSets>
          <reportSet>
            <reports><!-- select reports -->
              <report>index</report>
            </reports>
          <reportSet>
        </reportSets>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <reportSets>
          <reportSet><!-- by default, id = "default" -->
            <reports><!-- select non-aggregate reports -->
              <report>javadoc</report>
              <report>test-javadoc</report>
            </reports>
          </reportSet>
          <reportSet><!-- aggregate reportSet, to define in poms having modules -->
            <id>aggregate</id>
            <inherited>false</inherited><!-- don't run aggregate in child modules -->
            <reports>
              <report>aggregate</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

where:

The maven project info reports plugin is used to generate reports information about the project.

If you have included the appropriate <menu ref=“reports”/> tag in your site descriptor, then when you regenerate the site those items will appear in a menu called “Project Reports”.

site plugin

The apt, fml and xdoc format are recognized by default by the site plugin. If you want to add an other language, you must add the corresponding Doxia module dependency to the site plugin configuration.

Example with Markdown:

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version><!-- site plugin version --></version>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-twiki</artifactId>
            <version><!-- doxia version appropriate to the site plugin version --></version>
          </dependency>
          <dependency>
             <groupId>org.apache.maven.doxia</groupId>
              <artifactId>doxia-module-markdown</artifactId>
              <version>1.3</version>
           </dependency>
           <!-- Etc.... -->
        </dependencies>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Site.xml

The site.xml file is also known as the site decoration descriptor (in order to decorate the content of the pages).

Site Descriptor documentation
Reference
Xsd schema
The site.xml must be located in the directory: src/site/

The site.xml can contain some expressions, like ${project.name}. Each expression will be evaluated when the site is rendered.

Expressions can be:

${project.*}, for instance ${project.organization.name} referenced in <project><organization><name>
${project.properties}, for instance ${myProperty} referenced in <project><properties><myProperty>
${environmentVariable}, for instance ${JAVA_HOME}

<project xmlns="http://maven.apache.org/DECORATION/1.4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.4.0 http://maven.apache.org/xsd/decoration-1.4.0.xsd"
  name=.. >
  <bannerLeft>
    <name/>
    <src/>
    <alt/>
    <href/>
    <border/>
    <width/>
    <height/>
    <title/>
  </bannerLeft>
  <bannerRight>
    <name/>
    <src/>
    <alt/>
    <href/>
    <border/>
    <width/>
    <height/>
    <title/>
  </bannerRight>
  <googleAdSenseClient/>
  <googleAdSenseSlot/>
  <googleAnalyticsAccountId/>

  <publishDate position=.. format=.. />
  <version position=.. />
  <poweredBy>
    <logo name=.. href=.. img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. />
  </poweredBy>

  <!-- maven-fluido-skin. style, based on Twitter Bootstrap -->
  <!-- http://maven.apache.org/skins/maven-fluido-skin/ -->
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.3.0</version>
  </skin>
  
  <body>
    <head/>
    <links>
      <item name=.. href=.. img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. />
    </links>
    <breadcrumbs>
      <item name=.. href=.. img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. />
    </breadcrumbs>

    <menu name=.. inherit=.. inheritAsRef=.. ref=.. img=.. alt=.. position=.. border=.. width=.. height=.. title=.. >
      <item collapse=.. ref=.. name=.. href=.. img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. >
        <description/>
        <item>...recursion...<item>
      </item>
    </menu>
    
    <!-- There is also preset menus -->
    <!-- a menu with links to all the generated reports for your project -->
    <menu ref="reports" />
     
    <!-- a menu with a link to the parent project's site -->
    <menu ref="parent" />

    <!-- a menu containing the links to the sites of the submodules of this project -->
    <menu ref="modules" />
    
    <footer/>
  </body>

  <custom/>
</project>

Content

Creating content

Directory Structure

+- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- xdoc/
      |  +- other.xml
      |
      +- markdown/
      |  +- readme.md
      |
      +- A markup language ..../
      |  +- ....
      |
      +- site.xml

You can add any arbitrary resource by including them in a resources directory as shown below. Additional CSS files can be picked up when they are placed in the css directory within the resources directory.

+- src/
   +- site/
      +- resources/
         +- css/
         |  +- site.css
         |
         +- images/
            +- pic1.jpg

Generation

To generate the (web)site, just use the mvn tool with the site phase as argument:

default where the result will be generated in the following directory: target/site.

mvn site

to get multi-modular project site in one folder.

mvn site:stage -DstagingDirectory=C:\TEMP\fullsite

Doxia supports several output formats, the site plugin only creates XHTML.

After running 'mvn site:site' you will end up with this in your target directory:

+- target/
   +- site/
      +- css/
      |
      +- images/
      |
      +- index.html
      +- general.html
      +- faq.html
      +- other.html

The css and images directories contain stylesheets and images from the skin being used.

Documentation / Reference

Doxia