------ Configuring the Site Descriptor ------ Vincent Siveton Maria Odea Ching ------ November 2006 ------ ~~ 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/guides/mini/guide-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 <<>> which should be located in your <<>> directory. * 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 <<<$\{project.name\}>>> from your <<>> file as the "Site title". The title for this page is <"Maven Site plugin - Configuring the Site Descriptor">. If you want to use a different "Site title", but don't want to change the <<<\>>> in your <<>>, you can configure this in your <<>>, like this: +-----+ ... +-----+ * 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 <<<\>>> element to your <<>> like the following: +-----+ ... ... +-----+ The <<>> attribute can have one of these values: <<>>, <<>>, <<>>, <<>>, <<>>. * Powered by logo You can add your own "Powered by" logo to your site. To do this, you add a <<<\>>> element in your <<>> like this: +-----+ ... ... +-----+ * Inheritance Site descriptors are inherited along the same lines as project descriptors are. When you deploy a project, its site descriptor is also deployed so that it can be inherited. By default, only the basic settings are inherited. From the body, <> 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 <<>> attribute in the site descriptor. This can be either <<>> or <<>>, indicating where in the menu it will be placed after inheritance. For example: +-----+ ... ... ... ... ... +-----+ * 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: * <<>> - a menu with links to all the generated reports for your project * <<>> - a menu with a link to the parent project's site * <<>> - a menu containing the links to the sites of the submodules of this project [] To include a preset menu, use the <<>> attribute. For example: +-----+ ... ... ... ... +-----+ <> 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 maven-site-plugin. * 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 {{{creatingskins.html}Creating a Skin}}. To reference a skin in your project, you use the <<>> 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: +-----+ ... org.apache.maven.skins maven-classic-skin 1.0 ... +-----+ <> The <<<\>>> 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. * Expressions The <<>> 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.properties\}, for instance <<<$\{myProperty\}>>> referenced in <<< >>> * $\{environmentVariable\}, for instance <<<$\{JAVA_HOME\}>>> [] <> Support for some expressions, like <<<$\{project.name\}>>> are present in version 2.0-beta-5 of this plugin. Full support will be available in version 2.0-beta-6.