Built by Maven

Creating Content

Now it's time to create some content for your site. In Maven 2, the site content is structured by format, as there are several formats supported.

Documentation formats

Here's an example of a directory structure for a site:

+- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- markdown/
      |  +- markup.md
      |
      +- xdoc/
      |  +- other.xml
      |
      +- xhtml/
      |  +- xhtml-too.xhtml
      |
      +- xhtml5/
      |  +- xhtml5-content.xhtml5
      |
      +- site.xml

The ${basedir}/src/site directory which contains a site descriptor along with various directories corresponding to the supported document formats. Let's take a look at examples of the various document formats.

  • APT: The APT format ("Almost Plain Text") is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. A full reference of the APT Format is available.
  • FML: The FML format is the FAQ format. This is the same that were used in Maven 1.x. For more info about the FML Format check the Doxia site.
  • XDoc: The XDoc format is the same as used in Maven 1.x. A reference for the XDoc Format is available.
  • Markdown (since maven-site-plugin 3.3): Markdown is a widespread Markup language.

Other formats are available, but the above four are recognized by default by the site plugin. Any other document format for which a Doxia parser exists can be used as well (see the list of Doxia Markup Languages), but in this case you need to add the corresponding Doxia dependency to your site plugin configuration, as explained in the last paragraph. Note that Doxia also supports several output formats, the site plugin only creates XHTML5.

Note that all of the above is optional - just one index file is required in one of the input trees. The paths under each format will be merged together to form the root directory of the site. After running 'mvn site:site' on the example above you will end up with this in your target directory:

+- target/
   +- site/
      +- css/
      |
      +- images/
      |
      +- index.html
      +- general.html
      +- faq.html
      +- other.html
      +- xhtml-too.html
      +- xhtml5-content.html

This means that /src/site/apt/index.apt will be available in the site as /index.html. So, in your site descriptor you might link to /index.html and /other.html, where the source of these two files would be /src/site/apt/index.apt and /src/site/xdoc/other.xdoc.

The css and images directories contain stylesheets and images from the skin being used. You can read more about skins in the site descriptor documentation.

Adding Extra Resources

You can add any arbitrary resource to your site by including them in a resources directory as shown below. Additional CSS files can be picked up when they are placed in the css directory within the resources directory.

+- src/
   +- site/
      +- resources/
         +- css/
         |  +- site.css
         |
         +- images/
            +- pic1.jpg

The file site.css will be added to the default XHTML5 output, so it can be used to adjust the default Maven stylesheets if desired.

The file pic1.jpg will be available via a relative reference to the images directory from any page in your site.

Filtering

To filter properties into any supported documentation format, add a .vm extension to the filename.

For example, the module for the Maven website contains a content/xdoc/download.xml.vm file, which uses the expression ${currentStableVersion} to filter in a property set in the POM.

Note: Apache Velocity is used to apply the filtering.

Some properties are defined by default: see Doxia Site Renderer's Velocity processing reference for more information. For a complete usage overview, see Velocity's user guide.

Since version 3.5, you can save processed markup by setting saveProcessedContent to true: see corresponding documentation for more details.

Common Issues and Workarounds

  • dotted properties:

    As Velocity uses a dot-notation to traverse beans, you cannot use dotted properties defined in <properties> directly.

    It is generally advised to access properties by using the $context tool: e.g., with $context.get("my.property").

  • Markdown conflict with Velocity on ## syntax:

    Since ## denotes a single line comment in Velocity, Markdown headers using this syntax are suppressed from generated content.

    You can use unparsed content syntax #[[##]]# or escape tool like ${esc.h}${esc.h}.

Internationalization

Internationalization in Maven is very simple, as long as the reports you are using have that particular locale defined. For an overview of supported languages and instructions on how to add further languages, please see the related article Internationalization.

To enable multiple locales, or languages, add a configuration similar to the following to your POM:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.8.2</version>
        <configuration>
          <locales>en,fr</locales>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

This will generate both an English and a French version of the site. If en 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 fr/ subdirectory.

To add your own content for that translation instead of using the default, create a subdirectory with that locale's name in your site directory and create a new site descriptor with the name of the locale in the file name. For example:

+- src/
   +- site/
      +- apt/
      |  +- index.apt     (Default version)
      |
      +- fr/
      |  +- apt/
      |     +- index.apt  (French version)
      |
      +- site.xml         (Default site descriptor)
      +- site_fr.xml      (French site descriptor)

With one site descriptor per language, the translated site(s) can evolve independently.