------
 Usage
 ------
 Vincent Siveton
 <vincent.siveton@gmail.com>
 Maria Odea Ching
 ------
 17 July 2006
 ------

 ~~ Copyright 2006 The Apache Software Foundation.
 ~~
 ~~ Licensed under the Apache License, Version 2.0 (the "License");
 ~~ you may not use this file except in compliance with the License.
 ~~ You may obtain a copy of the License at
 ~~
 ~~      http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing, software
 ~~ distributed under the License is distributed on an "AS IS" BASIS,
 ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 ~~ See the License for the specific language governing permissions and
 ~~ limitations under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html


Usage

 Aside from the reports, you can put additional content (e.g. additional documentation, resources, etc.) in your site.
 See {{{http://maven.apache.org/guides/mini/guide-site.html}http://maven.apache.org/guides/mini/guide-site.html}}
 for more information on this.

* Generating a Site

  To generate the project's site and report distributions, execute

+-----+
mvn site
+-----+

* Deploying a Site

  The {{{deploy-mojo.html}site:deploy}} goal supports scp and file protocols. To deploy the generated site, you first need to specify where
  the site will be deployed. This can be set in the \<distributionManagement\> section of the pom as shown below.

+-----+
<project>
  ...
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <distributionManagement>
    <site>
      <id>maven.apache.org</id>
      <url>scp://maven.apache.org/deploy/path</url>
    </site>
  </distributionManagement>
  ...
</project>
+-----+

  Then execute the {{{deploy-mojo.html}site:deploy}} goal from your project.

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

  <<Note:>> A site must be generated first before executing site:deploy.

* Staging a Site

  <<Note:>> This goal is available in version 2.0-beta-5 or later of the Site plugin.

  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 the
  project and its modules.

  Just execute the {{{stage-mojo.html}site:stage}} goal from your project with the stagingDirectory parameter as shown below:

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

  <<Note:>> <<<stagingDirectory>>> can not be dynamic, i.e. stagingDirectory=$\{basedir\}\fullsite

  To stage a site and to deploy it, just execute the {{{stage-deploy-mojo.html}site:stage-deploy}} goal from your project
  with the required parameters. The <<<site:stage-deploy>>> goal will use the
  id <<<stagingSite>>> for deployment. So if you need to add your username or
  password in <<<settings.xml>>> you should use <<<\<id\>stagingSite\</id\>>>>
  for that <<<\<server\>>>> section. See the
  {{{http://maven.apache.org/guides/mini/guide-deployment-security-settings.html}Guide to Deployment and Security Settings}}
  for more information on this.

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

* Running a Site

  The Site plugin can also be used to start up the site in Jetty. To do this, execute

+-----+
mvn site:run
+-----+

  The server will, by default, be started on http://localhost:8080/. See
  {{{http://jetty.mortbay.org/jetty/index.html}http://jetty.mortbay.org/jetty/index.html}} for more information about
  the Jetty server.

* Filtering

  <<Note:>> This feature is available in version 2.0-beta-6 or later of the Site plugin.

  To filter properties into any supported documentation format, add a <<<.vm>>> extension to the filename.

  For example, the module for the Maven website contains a
  {{{http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/download.apt.vm}<<<src/site/apt/download.apt.vm>>>}}
  file, which uses the expression <<<$\{currentVersion}>>> to filter in a property set in the
  {{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.