How to use markdown for maven project site?

maven markdown maven-site-plugin
Paul Verest picture Paul Verest · Feb 12, 2013 · Viewed 14k times · Source

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.

Answer

Paul Verest picture Paul Verest · Feb 12, 2013

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

Related questions

No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?

I'm compiling a project in Eclipse using m2eclipse. I set the JDK path in Eclipse like this: Windows-->preferences-->installed jres--> jdk1.7.xx path But this is showing an error [ERROR] COMPILATION ERROR : [INFO] ------------------------------------------------------------- [ERROR] …

Read More
How to solve "Plugin execution not covered by lifecycle configuration" for Spring Data Maven Builds

I am trying to work with Spring Data and Neo4j. I started by trying to follow this guide linked to by the main site. In particular I based my pom.xml off of the "Hello, World!" example file. Here …

Read More
How to add local jar files to a Maven project?

How do I add local jar files (not yet part of the Maven repository) directly in my project's library sources?

Read More