Creating a Website for your Application
Now that you have walked though the process of building, testing and deploying Proficio, it is time for you to see how to create a standard Web site for an application. For applications like Proficio, it is recommended that you create a source directory at the top-level of the directory structure to store the resources that are used to generate the Web site. If you take a look, you will see that we have something similarly the following:
Figure 3-5: The site directory structure
Everything that you need to generate the Web site resides within the src/site directory. Within the src/site directory, there is a subdirectory for each of the supported documentation formats that you are using for your site and the very important site descriptor. Maven supports a number of different documentation formats to accommodate various needs and preferences.
Currently, the most well supported formats available are:
- The XDOC format, which is a simple XML format used widely at Apache.
- The APT format (Almost Plain Text), which is a wiki-like format that allows you to write simple, structured documents (like this) very quickly. A full reference of the APT Format is available.
- The FML format, which is the FAQ format. A simple XML format for managing FAQs.
- The DocBook Simple format, which is a less complex version of the full DocBook format.
Maven also has limited support for:
- The Twiki format, which is a popular Wiki markup format.
- The Confluence format, which is another popular Wiki markup format.
- The DocBook format.
We will look at a few of the more well-supported formats later in the chapter, but you should become familiar with the site descriptor as it is used to:
- Configure the appearance of the banner.
- Configure the skin used for the site.
- Configure the format of the publish date.
- Configure the links displayed below the banner.
- Configure additional information to be fed into the
<head/>element of the generated pages. - Configure the menu items displayed in the navigation column.
- Configure the appearance of project reports.
If you look in the src/site directory of the Proficio application and look at the site descriptor you will see the following:
<project name="Proficio">
<bannerLeft>
<name>Proficio</name>
<href>http://maven.apache.org/</href>
</bannerLeft>
<bannerRight>
<name>Proficio</name>
<src>http://maven.apache.org/images/apache-maven project.png</src>
</bannerRight>
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-default-skin</artifactId>
<version>1.0-SNAPSHOT</version>
</skin>
<publishDate format="dd MMM yyyy" />
<body>
<links>
<item name="Apache" href="http://www.apache.org/"/>
<item name="Maven" href="http://maven.apache.org/"/>
<item name="Continuum" href="http://maven.apache.org/continuum"/>
</links>
<head><meta name="faq" content="proficio"/></head>
<menu name="Quick Links">
<item name="Features" href="/maven-features.html"/>
</menu>
<menu name="About Proficio">
<item name="What is Proficio?" href="/what-is-maven.html"/>
</menu>
${reports}
</body>
</project>
This is a fairly standard Web site descriptor, but you should know about the specifics of each of the elements in the site descriptor:
Table 3-3: Site descriptor
| Site Descriptor Element | Description |
|---|---|
| bannerLeft and bannerRight | These elements take a name, href and optional src element, which can be used for images. |
| skin | This element looks very much like a dependency (the same mechanism is used to retrieve the skin) and controls which skin is used for the site. |
| publishDate | The format of the publish date is that of the SimpleDateFormat class in Java. |
| body/links | The link elements control the references that are displayed below the banner and take a simple name and href. |
| body/head | The head element allows you to insert anything in the head element of generated pages. You may wish to add metadata, or script snippets for activating tools like Google Analytics. |
| body/menu | The menu elements control the list of menus and their respective menu items that are displayed in the navigation column of the site. You can have any number of menu items each containing any number of links. |
| body/${reports} | The inclusion of the ${reports} reference controls whether the project reports are displayed in the web site. You might exclude ${reports} reference for a site that consists purely of user documentation for example. |
One of the most popular features of Maven are the standard reports that can be produced with little effort. If you simply include the ${reports} reference in your site descriptor you will, by default, have the standard project information reports generated and displayed automatically for you. The standard project information reports consist of the following:
- Dependencies Report
- Mailing Lists Report
- Continuous Integration Report
- Source Repository Report
- Issue Tracking Report
- Project Team Report
- License
Even though the standard reports are useful, often you will want to customize the projects reports that are created and displayed in your Web site. The reports created and displayed are controlled in the build/reports element in the POM. You may want to be more selective about the reports that you generate and to do so, you need to list each report that you want to include as part of the site generation. You do so by configuring the plugin as follows:
<project>
[...]
<reporting>
[...]
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<reportSets>
<reportSet>
<reports>
<report>dependencies</report>
<report>project-team</report>
<report>mailing-list</report>
<report>cim</report>
<!--
Issue tracking report will be omitted
<report>issue-tracking</report>
-->
<report>license</report>
<report>scm</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
[...]
</reporting>
[...]
</project>
Now that you have a good grasp of what formats are supported, how the site descriptor works, and how to configure reports, it’s time to generate your project’s web site. You can do so by executing the following command:
mvn site
After executing this command, you will end up with a directory structure (generated inside the target directory) with the generated content that looks like this:
Figure 3-6: The target directory
If you look at the generated site with your browser, this is what you will see:
Figure 3-7: The sample generated site
If you have resources like images or PDFs that you want to be able to reference in your documents you can use the src/site/resources to store them and when the site is generated the content of src/site/resources will be copied to the top-level directory of the site.
If you remember the directory structure for the the sources of our site, you will have noticed the src/site/resources directory, which contains an images directory, and as you can see in the directory listing above, it is located within the images directory of the generated site. Keeping this simple rule in mind, you can add any resources you wish to your site.