------
 Configuring the Site Descriptor
 ------
 Vincent Siveton
 <vincent.siveton@gmail.com>
 Maria Odea Ching
 Dennis Lundberg
 ------
 2010-08-12
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you 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/doxia/references/apt-format.html


Configuring the Site Descriptor

  You can create your own site descriptor for your project when you want to override the navigation tree for the site.
  For example, aside from the generated reports you want to add additional content to your site. In order for it
  to be accessible in the generated site, you must configure your site descriptor. You create the site descriptor in
  a file called <<<site.xml>>> which should be located in your <<<src/site>>> directory.

  If you are migrating from Maven 1.x you will be interested to know that the
  <<<navigation.xml>>> file has been replaced by the site descriptor in Maven 2.
  The format is nearly the same, so you can probably reuse most of your old file.

  There is an
  {{{http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/decoration.html}XML Schema Reference for the site descriptor}}
  available.

  The XML Schema for the site descriptor is published at {{http://maven.apache.org/xsd/decoration-1.0.0.xsd}}.

  Have a look at the
  {{{http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-site-plugin/src/site/site.xml}site descriptor for Maven Site Plugin}}
  for a real life example.

* Title

  The title of each generated page will be a combination of the <site title>
  and the title of the current page. By default the Site Plugin will use the
  value of the <<<\<name\>>>> element from your <<<pom.xml>>> file as the
  site title. The complete title for this page is "Maven Site Plugin - Configuring
  the Site Descriptor".

  If you want to use a different site title, but do not want to change the
  <<<\<name\>>>> element in your <<<pom.xml>>>, you can configure this in your
  <<<site.xml>>>, like this:

+-----+
<project name="My Site Title">
  ...
</project>
+-----+

* Publish Date

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

+-----+
<project>
  ...
  <publishDate position="right"/>
  ...
</project>
+-----+

  The <<<position>>> attribute can have one of these values: <<<left>>>,
  <<<right>>>, <<<navigation-top>>>, <<<navigation-bottom>>>, <<<bottom>>>.

  If you want hide the publish date, you can use this in your <<<site.xml>>>:

+-----+
<project>
  ...
  <publishDate position="none"/>
  ...
</project>
+-----+

  The format of the "Last Published" date is the ISO date format that is
  {{{http://www.w3.org/QA/Tips/iso-date}recommended by the W3C}}. Because the
  web has an international, cross-cultural audience it is recommended to <not>
  change the date format.

* Version

  You can show the "Version" of your project on the site, by adding a <<<\<version\>>>> element to your
  <<<site.xml>>> like this:

+-----+
<project>
  ...
  <version position="right"/>
  ...
</project>
+-----+

  The <<<position>>> attribute can have the same values as the <<<publishDate>>> attribute, see above.
  If the <<<position>>> attribute is omitted, the default value is <<<left>>>.

  If you want hide the version, you can use this in your <<<site.xml>>>:

+-----+
<project>
  ...
  <version position="none"/>
  ...
</project>
+-----+

* "Powered by" Logo

  You can add your own "Powered by" logo to your site.
  To do this, you add a <<<\<poweredBy\>>>> element in your <<<site.xml>>> like
  this:

+-----+
<project>
  ...
  <poweredBy>
    <logo name="Maven" href="http://maven.apache.org/"
          img="http://maven.apache.org/images/logos/maven-feather.png"/>
  </poweredBy>
  ...
</project>
+-----+

* Inheritance

  Site descriptors are inherited along the same lines as project descriptors
  are. If you want your project's site descriptor to be inherited, you need to
  attach it to the project's main artifact. You use the
  <<<site:attach-descriptor>>> goal to attach the site descriptor to your
  project's main artifact.

  In Maven 2 the site descriptor is attached automatically for projects with
  packaging set to "pom".

  By default, only the basic settings are inherited. From the body, <<only>>
  the links are inherited, and these accumulate to contain all the parents'
  site descriptor links.

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

+-----+
<project>
  ...
  <body>
    ...
    <menu name="My Inherited Menu" inherit="top">
      ...
    </menu>
    ...
  </body>
  ...
</project>
+-----+

* Including Generated Content

  Files in the format-based directory structure can be linked to by their target
  HTML filename, e.g. <<<${basedir}/src/site/apt/foo.apt>>> and
  <<<${basedir}/src/site/fml/faq.fml>>> can be linked to via:

+-----+
<project>
  ...
  <body>
    ...
    <menu name="Foo" href="foo.html" />
    <menu name="FAQ" href="faq.html" />
    ...
  </body>
  ...
</project>
+-----+

  There are also several preset menus that can be used in the site descriptor to
  include generated content from your project. These are linked via the
  <<<ref>>> attribute, like so:

+-----+
<project>
  ...
  <body>
    ...
    <menu ref="modules" />
    ...
  </body>
  ...
</project>
+-----+

  <<Note:>> The old syntax using <<<$\{reports\}>>>, <<<$\{parent\}>>> and
  <<<$\{modules\}>>> has been deprecated and you are encouraged to use the new
  syntax instead. The support for the old syntax will be removed in a future
  version of the Site Plugin.

  The currently available preset menus are:

  * <<<reports>>> - a menu with links to all the generated reports for your
  project

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

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

  []


* Skinning

  Skins can be created to customize the look and feel of a site in a consistent way. For more information on creating a
  skin, see {{{./creatingskins.html}Creating a Skin}}. To use a specific skin in 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
  {{{http://maven.apache.org/skins/maven-classic-skin/}Maven Classic Skin}}, you would include:

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

  <<Note:>> The <<<\<version\>>>> element is optional and, like plugins, if
  omitted the latest version available will be used. It is recommended that you
  always specify a version so that your site is reproducible over time.

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

  If you don't specify a skin, the Site Plugin will use
  {{{http://maven.apache.org/skins/maven-default-skin/}Maven Default Skin}}.

* Expressions

  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\}>>>

  []

  <<Note:>> Support for some expressions, like <<<$\{project.name\}>>> is present in
  version 2.0-beta-5 of this plugin. Full support is available since version
  2.0-beta-6.