如何在maven项目网站上使用markdown？

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

如何使用maven和markdown标记语言开始项目文档？ Maven站点默认是APT，这对于学习maven方式来说是不舒服的。（通常团队中的任何人都不会开始编写maven站点文档，因为他们还需要在此过程中学习一种标记语言。）

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?

有没有人试图使用markdown（与github上使用的标记语言相同）来获取Maven项目站点文档？我从Maven Doxia的参考文献中看到它是可能的。有什么问题？

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.

我是maven网站一代的新手。我认为markdown最好先于其他标记语言开始，团队还没有合作过。

UPDATE. Succeeded. See answer below.

UPDATE。成功了。见下面的答案。

2 个解决方案

#1

Quote from http://maven.apache.org/doxia/references/index.html

引自http://maven.apache.org/doxia/references/index.html

Add this to pom.xml

将其添加到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:

然后开始在src / site / markdown /扩展名为.md的情况下添加页面。对于每个页面添加菜单项，如下面的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>

Than use mvn site to generate site. Look at target/site to review results.

比使用mvn网站生成网站。查看目标/站点以查看结果。

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

mvn site：stage -DstagingDirectory = C：\ TEMP \ fullsite，在一个文件夹中获取多模块化项目站点。

#2

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

另一种标准方法是使用Maven Site Plugin，如下所示

http://maven.apache.org/plugins/maven-site-plugin/
http://maven.apache.org/plugins/maven-site-plugin/
http://illegalexception.schlichtherle.de/2013/06/17/how-to-use-markdown-syntax-with-the-maven-site-plugin/
http://illegalexception.schlichtherle.de/2013/06/17/how-to-use-markdown-syntax-with-the-maven-site-plugin/

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

使用此方法，您可以利用速度模板引擎过滤。因此，它为您的文档增加了更多功能。

#1