Architecture

The Site Plugin uses:

• Doxia to parse many markup languages then render HTML: see Creating Content documentation for more details (particularly which markups are enabled by default in maven-site-plugin and how to add one),
• Doxia Sitetools - Site Renderer to integrate document content into a template packaged as a skin: see Creating Skins documentation for more details,
• Maven Reporting Executor to manage reports execution (since Maven 3).

Goals Overview

The Site Plugin has the following goals:

• site:site is used generate a site for a single project. Note that links between module sites in a multi module build will not work, since local build directory structure doesn't match deployed site.
• site:deploy is used to deploy the generated site using Wagon supported protocol to the site URL specified in the <distributionManagement> section of the POM.
• site:run starts a server, rendering documents on-demand (while requested) for faster previews. It uses Jetty as the web server.
• site:stage generates a site in a local staging or mock directory based on the site URL specified in the <distributionManagement> section of the POM. It can be used to test that links between module sites in a multi module build work. This goal requires the site to already have been generated using the site goal, such as by calling mvn site.
• site:stage-deploy deploys the generated site to a staging or mock directory to the site URL specified in the <distributionManagement> section of the POM.
• site:attach-descriptor adds the site descriptor (site.xml) to the list of files to be installed/deployed. For more references of the site descriptor, here's a link.
• site:jar bundles the site output into a JAR so that it can be deployed to a repository.
• site:effective-site calculates the effective site descriptor, after inheritance and interpolation.
• site:auto-refresh renders the site once and then watches for changes in the source files. If a change is detected, the Doxia source will be re-rendered.

Usage

General instructions on how to use the Site Plugin can be found on the usage page. Some more specific use cases are described in the examples given below.

In case you still have questions regarding the plugin's usage, please have a look at the FAQ and feel free to contact the user mailing list. The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the mail archive.

If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our issue tracker. When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs, or, most preferably, little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our source repository and will find supplementary information in the guide to helping with Maven.

Examples

The following examples show how to use the Site Plugin in more advanced use cases:

• Creating Content
• Configuring the Site Descriptor
• Using Mermaid Diagrams
• Configuring Site Run
• Excluding Document Formats