You can integrate your static pages by following these steps:
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.
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.
The Site Plugin does not use the <url> element in the POM. The project URL is just a piece of information to let your users know where the project lives. Some other plugins (e.g. the project-info-report-plugin) may be used to present this information. 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.
On the other hand, the <distributionManagement.url> is used in a multi-module build to construct relative links between the generated sub-module sites. 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 ("/").
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:
<links> <item name="Your Site" href="http://www.your.site.com/"/> <item name="Maven 2" href="http://maven.apache.org/maven2/"/> </links>
There is an issue for this in JIRA, where you can read more about this.
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.
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.