Menu
How to start with project documentation using maven and markdown markup language? Maven site default is APT, which is uncomfortable to learn just to do thing maven way. (Usually nobody in a team will start writing maven site documentation when they also need to learn one more markup language along the way.)
Has anybody tried to use markdown (the same markup language as used on github) for Maven project site documentation? I see from Maven Doxia references that it is possible. Any issues?
I am new to maven site generation. I think markdown is better to start with, than others markup languages, that the team has not worked with.
UPDATE. Succeeded. See answer below.
457
To generate a site, just run mvn site:site or mvn site. To view the generated site on a local machine, run mvn site:run. This command will deploy the site to a Jetty web server at the address localhost:8080.
The Site Plugin is used to generate a site for the project. The generated site also includes the project's reports that were configured in the POM.
Maven was built with the understanding that documentation needs to be automated and has been progressively improved throughout updates to the maven project. The most common case for Maven site docs is to deploy generated documentation to an external web server via SCP, FTP, WebDAV or SFTP.
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.
Quote from http://maven.apache.org/doxia/references/index.html
Add this to pom.xml
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.2</version> <dependencies> <dependency> <groupId>org.apache.maven.doxia</groupId> <artifactId>doxia-module-markdown</artifactId> <version>1.3</version> </dependency> </dependencies> </plugin> Then start adding pages under src/site/markdown/ with .md extension. For every page add menu item like in sniplet below:
<body> <!-- http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/decoration.html <item collapse=.. ref=.. name=.. href="README" img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. > --> <menu name="User guide"> <item href="README.html" name="README" /> </menu> <menu ref="reports" inherit="bottom" /> </body> Than use mvn site to generate site. Look at target/site to review results.
mvn site:stage -DstagingDirectory=C:\TEMP\fullsite to get multi-modular project site in one folder.
Read more about maven-site-plugin.
I recommend to use maven-fluido-skin. It is newest style, based on Twitter Bootstrap Add this to site.xml
<project name="xxx"> [...] <skin> <groupId>org.apache.maven.skins</groupId> <artifactId>maven-fluido-skin</artifactId> <version>1.3.0</version> </skin> [...] </project> See also https://github.com/winterstein/Eclipse-Markdown-Editor-Plugin
183
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With