Best IT Recipes

How to use markdown for maven project site?

How to start with project documentation using maven and markdown markup language? The default Maven site is APT, which is inconvenient to learn how to just do maven stuff. (Normally, no one on the team will start writing documentation on the maven site when they also need to learn another markup language along the way.)

Has anyone tried to use markdown (the same markup language as on github) to document the Maven project site? I see from Maven Doxia links that this is possible. Any problems?

I am new to maven website. I think it's better to start markdown with other markup languages ​​that the team didn't work with.

UPDATE Successor. See answer below.

+43
maven markdown maven-site-plugin
Feb 12 '13 at 9:22
source share
2 answers

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 add the pages under src/site/markdown/ with the extension .md . For each page, add a menu item, for example, in sniplet:

  <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>

How to use mvn site to create a site. See target/site for results.

mvn site:stage -DstagingDirectory=C:\TEMP\fullsite to get a multi-module project site in one folder.

Learn more about maven-site-plugin .

I recommend using maven-fluido-skin . This is the latest Twitter Bootstrap based style. Add this to your .xml site.

 <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

+61
Feb 12 '13 at 11:25
source share
— -

Another standard way is to use the Maven Site Plugin , as shown below.

With this approach, you can use the filtering engine speed patterns. Thus, it adds more features to your documentation.

+3
Feb 04 '15 at 23:53
source share


More articles:


All Articles