------ Generating a Site ------ Brett Porter Jason van Zyl ------ 13 May 2005 ------ Building a Site * Creating Content The first step to creating your site is to create some content. In Maven 2.0, the site content is separated by format, as there are several available. ------------------- +- src/ +- site/ +- apt/ | +- index.apt | +- xdoc/ | +- other.xml | +- fml/ | +- general.fml | +- faq.fml | +- site.xml -------------------- The Xdoc format is the same as {{{http://maven.apache.org/using/site.html} used in Maven 1.0}}. However, <<>> has been replaced by the site descriptor (see below). The APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this) very quickly. A full reference of the {{{apt-format.html} APT Format}} is available. The FML format is the FAQ format, also used in Maven 1.0. Other formats are available, but at this point these 3 are the best tested. There are also several possible output formats, but as of alpha-2, only XHTML is available. Note that all of the above is optional - just one index file is required in one of the input trees. Each of the paths will be merged together to form the root directory of the site. * Generating The Site Generating the site is very simple, and fast! --------------- m2 site:site --------------- The resulting site will be in <<>> For more information on the site plugin, see the {{{plugins/maven-site-plugin/} plugin reference}}. * Deploying The Site To be able to deploy the site, you must first declare a location to distribute to in your <<>>, similar to the repository for deployment. --------------- website scp://www.mycompany.com/www/docs/project/ --------------- The <<>> element identifies the repository, so that you can attach credentials to it in your <<>> file in the same way as you would for any other repository. The URL gives the location to deploy to. Currently, only SSH is supported, as above which copies to the host <<>> in the path <<>>. Deploying the site is done with the <<>> goal. Note that you cannot just call the deployment goal on its own, however. You must presently run the <<>> goal independantly. --------------- m2 site:site site:deploy --------------- <> the trailing slash in the URL above indicates that any subprojects that inherit this value should append their artifact ID to the path instead of using it as is. * Creating a Site Descriptor The <<>> file is used to describe the layout of the site, and replaces the navigation file used in Maven 1.0. A sample is given below: -------------------- Maven http://maven.apache.org/images/apache-maven-project.png http://maven.apache.org/ http://maven.apache.org/images/maven-small.gif ${reports} ... -------------------- ~~TODO: deserves more explanation. Note the <<<${reports}>>> string in the navigation. When building the site, this is replaced by menus for any reports that you have configured. * Adding Extra Resources You can add any arbitrary resources to you site by including them in a <<>> directory as shown below. Addition CSS will be picked up when they are placed in the <<>> directory within the <<>> directory. ------------------- +- src/ +- site/ +- resources/ +- css/ | +- site.css | +- images/ +- pic1.jpg -------------------- The file <<>> will be added to the default XHTML output, so can be used to adjust the default Maven stylesheets if desired. The file <<>> will be available via a relative reference to the <<>> directory from any page in your site. * Configuring Reports Maven has several reports that you can add to your web site to display the current state of the project. These reports take the form of plugins, just like those used to build the project. To add these reports to your site, you must add the plugins to a special <<>> section in the POM. The following example shows how to configure the standard project information reports that display information from the POM in a friendly format: ------------------- ... org.apache.maven.reports maven-project-info-reports-plugin ... ------------------- If you have included the appropriate <<<${reports}>>> tag in your <<>> descriptor, then when you regenerate the site those items will appear on the menu. ~~TODO: explain report sets * Internationalisation Internationalisation in Maven is very simple, as long as the reports you are using have that particular locale defined. To enable multiple locales, add configuration similar to the following to your POM: ------------------- ... org.apache.maven.plugins maven-site-plugin en,fr ... ------------------- This will generate both an English and a French version of the site. If <<>> is your current locale, then it will be generated at the root of the site, with a copy of the French translation of the site in the <<>> subdirectory. To add your own content for that translation instead of using the default, place a subdirectory with that locale name in your individual content directories. For example: ------------------- +- src/ +- site/ +- apt/ | +- fr/ | | +- index.apt (French version) | +- index.apt (Default version) +- site.xml -------------------- ~~TODO: what about translating site.xml?