Frequently Asked Questions

General

  1. What is the difference between mvn site and mvn site:site?
  2. How do I Integrate static (X)HTML pages into my Maven site?
  3. How to include a custom Doxia module, like Twiki?
  4. How can I validate my xdoc/fml source files?
  5. How does the Site Plugin use the <url> element in the POM?

Specific issues

  1. Why do my absolute links get translated into relative links?
  2. Why don't the links between parent and child modules work when I run "mvn site"?
  3. Can I use entities in xdoc/fml source files?

General

What is the difference between mvn site and mvn site:site?
mvn site
Calls the site lifecycle with the associate phases (i.e. pre-site, site, post-site, site-deploy). See Lifecycle Reference.
mvn site:site
Calls the site goal from the site plugin. See site:site.

[top]

How do I Integrate static (X)HTML pages into my Maven site?

You can integrate your static pages by following these steps:

  • Put your static pages in the resources directory, ${basedir}/src/site/resources
  • Create your site.xml and put it in ${basedir}/src/site
  • Link to the static pages by modifying the menu section, create items and map them to the filenames of the static pages

[top]

How to include a custom Doxia module, like Twiki?

The site plugin handles out-of-box apt, xdoc and fml formats. If you want to use a custom format like Twiki, Simple DocBook, or XHTML (or any other document format for which a doxia parser exists, see the list of Doxia Markup Languages), you need to specify the corresponding Doxia module dependency, e.g. for Twiki: 

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-twiki</artifactId>
            <version><!-- doxia version appropriate to the site plugin version --></version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Note that the doxia version has to be adjusted to the site-plugin version you are using, see the Migration Guide. In particular, for site plugin versions >=2.1 you need to use doxia >=1.1.

[top]

How can I validate my xdoc/fml source files?

Since version 2.1.1 of the Site Plugin, there is a validate configuration parameter that switches on xml validation (default is off). Note that in the current implementation of the parser used by Doxia, validation requires an independent parsing run, so that every source file is actually parsed twice when validation is switched on.

If validation is switched on, all xml source files need a correct schema and/or DTD definition. See the Doxia documentation on validating xdocs, and the schema definitions for xdoc and fml.

[top]

How does the Site Plugin use the <url> element in the POM?

The Site Plugin uses the <url> element in the POM to create relative links for the generated site. If your project has a URL where the generated site is deployed, then put that URL into the <url> element. If the project's site is not deployed anywhere, then remove the <url> element from the POM.

In a multi module build it is important for the parent and child modules to have different URLs. If they have the same URL, then links within the combined site will not work. Note that a proper URL should also be terminated by a slash ("/").

[top]

Specific issues

Why do my absolute links get translated into relative links?

This happens because the Site Plugin tries to make all URLs relative, when possible. If you have something like this defined in your pom.xml: 

<url>http://www.your.site.com/</url>
and create links in your site.xml (just an example) like this: 
<links>
  <item name="Your Site" href="http://www.your.site.com/"/>
  <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
</links>
You will see that the link to "Your site" will be a relative one, but that the link to "Maven 2" will be an absolute link.

There is an issue for this in JIRA, where you can read more about this.

[top]

Why don't the links between parent and child modules work when I run "mvn site"?

What "mvn site" will do for you, in a multi-project build, is to run "mvn site" for the parent and all its modules individually. The links between parent and child will not work here. They will however work when you deploy the site.

If you want to test this, prior to deployment, you can run the site:stage goal as described in the usage documentation instead.

[top]

Can I use entities in xdoc/fml source files?

Yes. Entity resolution has been added in Doxia version 1.1, available in Site Plugin 2.1 and later.

There is a catch however. In the current implementation (as of maven-site-plugin-2.1.1), entities are only resolved by an independent validation run. Therefore, if you want to use entities, you have to switch on validation for your xml source files. See MSITE-483.

[top]