将文档添加到我的 Maven 站点报告答案

【问题标题】：Adding document to my Maven site report将文档添加到我的 Maven 站点报告
【发布时间】：2015-07-10 21:17:57
【问题描述】：

我们希望在我们的 Maven 站点报告中提供一个位于 Markdown 中的文档。我找到了一个将 Markdown 翻译成 HTML 的插件，并将生成的 HTML 文档放在target/documents/README.html 中。我想将此文档包含在生成站点报告中，但是 maven-site-plugin 的文档有点稀疏：

如何将静态 (X)HTML 页面集成到我的 Maven 站点中？您可以按照以下步骤集成静态页面：

将静态页面放在资源目录 ${basedir}/src/site/resources

创建您的 site.xml 并将其放入 ${basedir}/src/site

通过修改菜单部分链接到静态页面，创建项目并将它们映射到静态页面的文件名

哇，这很清楚！

此文档存储在${basedir}/src/markdown/README.md 中，并在target/documents/README.html 中生成为HTML 文档。我可以更改所有发生的目录，但我不想将生成的 HTML 文档写入${basedir}/src/site。

如何生成自己的site.xml？我可以让site.xml 从target 下的另一个目录中提取文档吗？

【问题讨论】：

只需将文档放入 src/site/markdown/.. 就可以了（如果您使用的是最新版本的 maven-site-plugin，请注意。
这行得通——部分可行。它会生成一个文件target/site/README.html，但我找不到指向该特定页面的链接。
您需要在其他页面或src/site/site.xml 描述符中创建链接...
@khmarbaise - 我实际上从某人那里得到了一个site.xml 的例子。文档没有说明的是它将菜单项预先挂在现有的index.html 页面上。也就是说，我不必重新创建整个索引，只需放置我需要的链接。稍后我会添加完整的答案。

标签： maven maven-site-plugin

【解决方案1】：

最终并没有我想象的那么困难。 site.xml 文档很糟糕，但我找到了一个示例，玩弄了它，并想出了如何去做：

首先，我听从了khmarbaise 的建议，将文档放在src/site/markdown/README.md 下。当site 运行时，这会产生一个target/site/README.html 文档。但是，没有指向它的链接。

接下来我要做的是生成一个src/site/site.xml 文件。我所要做的就是创建所需的链接，而不是整个 index.html 页面：

<?xml version="1.0" encoding="ISO-8859-1"?>
<project>
    <body>
        <menu name="Configuration">
            <item name="Using this library" href="README.html"/>
        </menu>
        <menu ref="reports"/>
    </body>
</project>

需要<menu ref="reports"/> 来保留其他报告菜单。

您可以在此处查看结果：

注意添加的配置部分。

我唯一做的另一件事是使用技术规则markdown plugin。这样，我可以将生成的 HTML 链接到 Jenkins 中的存档工件链接。

【讨论】：

如果您提到的文档不好，您有什么改进建议吗？可能是您根据您的建议创建一个合适的JIRA ticket，以便使文档变得更好。