46

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.

Paul Verest
  • 51,779
  • 39
  • 174
  • 288
  • Not yet. I have planned to do that before end of February. I will post my own answer here, if nobody answers. – Paul Verest Feb 12 '13 at 09:43
  • 1
    The link you posted has all the information you need. I'll mark this question to be closed in the mean time. Please post if you have a more specific question when you do try to generate the documentation with md. – Augusto Feb 12 '13 at 09:49
  • In Maven the default is apt oder xdoc format ...currently there is no maven-plugin to handle GitHub Markdown. – khmarbaise Feb 12 '13 at 10:25

2 Answers2

65

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

Paul Verest
  • 51,779
  • 39
  • 174
  • 288
  • 5
    This post needs to be added to the Doxia documentation since it's not clear to those of us who have not used Maven to manage documentation how this is done. Thanks. – Richard Clayton Jun 20 '13 at 13:05
  • 2
    Open-source example https://github.com/Nodeclipse/nodeclipse-1/tree/master/src/site – Paul Verest Sep 05 '13 at 05:53
  • 1
    Thanks for this. I was looking for Markdown for generating site using Maven, and this works perfectly! – tuxdna Jan 16 '14 at 14:18
  • Ask question on stackoverflow.com :) using similar tags, and possibly referencing this question. – Paul Verest Feb 04 '14 at 14:38
  • I added several futher informations to my project: issueManagement, ciManagement, organization, scm and description. If these are added - the doxia-Plugin will not get fired and markdown is not compiled. Just wantet to add this - perhaps somebody has the same error(?). – cljk Aug 11 '16 at 06:08
5

Another standard way is to use the Maven Site Plugin as follows

With this approach, you can take advantage of the velocity template engine filtering. So it adds more power to your documentation.

gillesB
  • 839
  • 1
  • 8
  • 27
EliuX
  • 7,605
  • 4
  • 35
  • 37
  • 2
    This approach take advantages of the velocity template engine filtering that the site plugin does http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html#Filtering Apparently, your markdown can reference to maven variables like ${project.name} – xverges May 21 '15 at 05:19