maven插件生成代码_使用Maven网站插件从Markdown生成HTML文档-CSDN博客

maven插件生成代码

准备易于维护的可读文档不是一件容易的事，对于大多数开发人员来说也不是最喜欢的。从简单的文件（例如纯文本文件）到更复杂的文件（例如Sphinx generator），我们可以选择多种创建文档的方法。它们每个都有自己的优点和缺点。纯文件易于维护，不需要任何特殊文件，但不适用于现代网络。另一方面，Sphinx是用于准备专业文档的高级解决方案，但需要第三方工具。

对于使用Apache Maven构建项目的Java开发人员来说，使用相同的工具生成文档将是最方便的。在site生命周期阶段，Maven运行站点插件，该插件从源文件生成文档。输出HTML站点在许多情况下很有用，但它不是非常用户友好的。默认情况下，源文件必须以APT格式保存，尽管如今我们更喜欢使用Markdown或reStructuredText。

幸运的是， maven-site-plugin允许进行一些自定义，我们使用这些自定义来从markdown文件生成简单的文档站点。在Github上可以找到示例项目。

HTML模板

默认情况下，Maven站点插件使用的是Velocity模板，该模板随Doxia一起提供（Maven内部用于生成内容的框架）。为了我们的目的，我们需要一些更简单的东西，因此我们准备新模板并将其另存为src/site/目录中的dev-to-template.vm 。

<!DOCTYPE html>
<html>
  <head>
    <meta charset= "utf-8" />
  </head>
  <body>
    <a href= "index.html" > Start </a>
    #*   *#$bodyContent
  </body>
</html>

变量$bodyContent引用呈现Markdown文件的输出，该文件必须保存在目录src/site/markdown 。

模块配置

我们需要在模块pom.xml调整maven-site-plugin配置

<plugin>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.8.2</version>
  <configuration>
    <generateReports>false</generateReports>
    <templateFile>src/site/dev-to-template.vm</templateFile>
    <relativizeDecorationLinks>false</relativizeDecorationLinks>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.doxia</groupId>
      <artifactId>doxia-module-markdown</artifactId>
      <version>1.9</version>
    </dependency>
   </dependencies>
 </plugin>

通过属性templateFile我们指向创建的模板文件。当插件依赖doxia-module-markdown ，它将在目录src/site/markddown搜索Markdown文件，并将其用于生成HTML标记。

内容生成通过命令./mvnw site触发，HTML输出保存在目录target/site/ 。通过示例模板，我们可以通过简单的导航获得HTML文档。如果有需要，应该可以轻松添加更多定制。最重要的是，我们不需要任何额外的工具来生成内容。