Here's a way to publish the README and CHANGELOG markdown files on the project's Maven Site:
In the Site descriptor (/src/site/site.xml) reference the files you want to publish:
<?xml version="1.0" encoding="UTF-8"?>
<project>
<body>
<menu name="Documentation">
<item name="README" href="docs/README.html"/>
<item name="CHANGELOG" href="docs/CHANGELOG.html" />
</menu>
</body>
</project>In the pre-site build phase copy the files to the markdown resource directory. The site plugin transforms the documentation to HTML and outputs it to the corresponding target directory.
After the site building finished, clean up the duplicate files:
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<configuration>
<encoding>${project.build.sourceEncoding}</encoding>
</configuration>
<executions>
<execution>
<!-- Copy the readme and such files to the site source files so that a page is generated from it. -->
<id>copy-docs</id>
<phase>pre-site</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/src/site/markdown/docs</outputDirectory>
<resources>
<resource>
<directory>${basedir}</directory>
<includes>
<include>README.md</include>
<include>CHANGELOG.md</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<!-- Delete the markdown/docs directory to remove the readme and such duplicate files from the site source files. -->
<executions>
<execution>
<id>clear-docs</id>
<phase>site</phase>
<goals>
<goal>clean</goal>
</goals>
<configuration>
<filesets>
<fileset>
<directory>src/site/markdown/docs</directory>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
<excludeDefaultDirectories>true</excludeDefaultDirectories>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
...
</project>To show the process in terms of file structure:
The normal state:
.
+-- src
| +-- site
| | +-- site.xml.
+-- src
| +-- site
| | +-- markdown
| | | +-- docs
| | | | +-- README.md
| | | | +-- CHANGELOG.md
| | +-- site.xml.
+-- docs
| +-- README.html
| +-- CHANGELOG.html
+-- index.html
A bonus note regarding the deployment url: it can be changed it the distributionManagement section:
<project>
...
<distributionManagement>
<site>
<url>${maven.reports.deployBase}/${project.groupId}</url>
</site>
</distributionManagement>
...
</project>
No comments:
Post a Comment