------
 Maven 2 Site Plugin
 ------
 Vincent Siveton
 <vincent.siveton@gmail.com>
 ------
 December 8, 2005
 ------

Maven 2 Site Plugin

  Generate the project's site and report distributions.
  You could also have a look at this mini-guide {{{http://maven.apache.org/guides/mini/guide-site.html}http://maven.apache.org/guides/mini/guide-site.html}}.

*How to Use Site plugin

  Using the site plugin is very easy, just execute the site goal from your project

-------------------
  mvn site
-------------------

  and it would generate its default reports.

*How to Deploy Site plugin

  To deploy the generated site, just execute the site:deploy goal from your project.

-------------------
  mvn site-deploy
-------------------

*How to change the site template

  It is possible to change the Velocity template used for creating the site.
  In your pom, just add something like this:

-------------------
  ...
  <reporting>
    <plugins>
      <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-site-plugin</artifactId>
       <configuration>
         <templateDirectory>${basedir}</templateDirectory>
         <template>maven-site.vm</template>
       </configuration>
      </plugin>
    </plugins>
  </reporting>
  ...
-------------------

  And execute the site goal from your project.

*How to Staging Site plugin

  <<This goal is only available in version 2.0 of the Site plugin and above>>

  To review/test the generated Web site before an official deploy, you could stage the site in
  a specific directory. It will use the distributionManagement elements or the project hierarchy to link
  project and its modules.
  Just execute the site:stage goal from your project with the stagingDirectory parameter.

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

  Note: stagingDirectory could not by dynamic, i.e. stagingDirectory=$\{basedir\}\fullsite


  To stage a site and to deploy it, just execute the site:stage goal from your project with required
  parameters.

-------------------
  mvn site:stage-deploy -DstagingDirectory=C:\fullsite \
    -DstagingSiteURL=scp://www.mycompany.com/www/project/
-------------------

*Site Descriptor

  For more references of site descriptor, here's a link {{{http://maven.apache.org/site.html}http://maven.apache.org/site.html}}.

  With the out-of box Velocity template, the "Last Published" position could be configurable.
  By default, the position is on the left but you could change it.
  To do this, you could add a \<publishDate/> in the site.xml like this following:

-------------------
<project name="My Site Descriptor">
  ...
  <publishDate position="navigation-bottom" format="MM-dd-yy"/>
  ...
</project>
-------------------

  The position could be: left, right, navigation-top, navigation-bottom, bottom.

*Inheritance

  Site descriptors are inherited along the same lines as project descriptors are. When you deploy a project, it's site
  descriptor is also deployed so that it can be inherited.

  By default, only the basic settings are inherited. From the body, only the links are inherited, and these accumulate
  to contain all of the descriptor's links.

  However, it is possible to inherit menus as well. To do so, use the <<<inherit>>> flag of the site descriptor. This can
  be either <<<top>>> or <<<bottom>>>, indicating where in the menu it will be placed after inheritance. For example:

----------
 ...
  <menu name="Common Links" inherit="top">
    ...
  </menu>
 ....
----------

*Including Generated Content

  There are several preset menus that can be used in the site descriptor to include generated content from your project.
  These are:

    * <<<reports>>> - the reports menu for all of the generated reports from your project

    * <<<parent>>> - a menu with a link to the parent project's site

    * <<<modules>>> - a menu containing the submodules of this project and links to their sites.

  To include a preset menu, use the <<<ref>>> attribute. For example:

----------
 ...
  <menu ref="modules" />
 ....
----------

*Skinning

  Skins can be created to customise the look and feel of a site in a consistent way. For more information on creating a
  skin, see {{{creating-a-skin.html}Creating a Skin}}. To reference a skin from your project, you use the <<<skin>>>
  element of the site descriptor. This is a regular artifact or dependency-like element. For example, to use the Classic
  Maven skin, you'd include:

----------
 ...
  <skin>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-classic-skin</artifactId>
    <version>1.0</version>
  </skin>
 ....
----------

  Note that the version is optional and, like plugins, if omitted the latest version available will be used.

  This skin will copy the necessary resources including CSS and if necessary use the included alternate Velocity
  template to render the site.