在 github 页中包含基于 pom.xml 的版本号？

Question

我有一个 Java 基于 Maven 的 project on GitHub, where I maintain documentation on GitHub Pages。

我在两个地方提到了我的maven项目的版本号。目前我用版本号手动更新 index.md and readme.md （在一页上多次）。

版本号有没有单一来源的方法？

其中之一：

小解决方案：在页面顶部定义它。
中等解决方案：为文档定义一次（挑战：文档的 /doc 与 readme.md 运行不同 (?)）
最佳解决方案：阅读 pom.xml

不胜感激

Answer 1

问题是这些文件是在两种不同的上下文中访问的：README.md 仅在 GitHub 本身或您的存储库副本中真正读取。在 Jekyll 处理后，index.md 文件被转换为 index.html 文件并在您的网页上查看。

Small solution: define it on top of the pages.

同样，问题是 README.md 没有被处理成 HTML，所以将它添加到前面的内容不会神奇地将它添加到内容中。

Medium solution: define it once for documentation (challenge: /doc for documentation runs different (?) from readme.md)

您还有README.md没有处理的问题。这只是基本文本。

Best solution: read it from pom.xml

您不能从 GitHub 页面执行此操作，除非您在 Jekyll 站点中将 pom.xml 设为 post。这几乎肯定不是您想要做的。

您或许可以找到一个 Maven Jekyll 插件来为您创建网页内容。如果是这样，那么您可能可以将 pom.xml 中的变量注入到 Jekyll 中。然后，您将放弃自动为您调用 Jekyll 的 GitHub 个页面。

但老实说，听起来您有点想多了。如果我是你，我会继续使用手动更改它的简单工作流程。您可以在 index.md 中使用 frontmatter，只需要在一个地方指定它。

Answer 2

有一种方法可以使用 maven-resources-plugin 提供的过滤功能，但我觉得有点老套。

首先，您想要项目版本的任何文档都需要放在最终文档的单独位置（例如名为 doc-templates 的文件夹）。在这些文件中，将项目版本替换为 @project.version@，这是 Maven 在其过滤步骤中识别的标记。

然后你可以添加一个插件配置，将模板文档视为过滤资源并将它们输出到最终文档位置；例如：

<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${basedir}/docs</outputDirectory>
                <resources>
                    <resource>
                        <directory>doc-templates</directory>
                        <includes>
                            <include>file-with-version.md</include>
                        </includes>
                        <filtering>true</filtering>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

注意它将这次执行的输出目录设置为${basedir}/docs； ${basedir} 对我来说解析为项目的根目录（pom.xml 所在的目录），因此此配置使 Maven 将资源输出到您的文档目录中。

使用 Maven 资源过滤的优点是您还可以在文档中自动包含其他变量（甚至系统变量！）。

你需要记住运行 mvn package 在你提交你的文档之前运行s maven 也会提交你的文档作为任何构建管道更新文档但不会提交它（除非你让它这样做）。

更新：我刚刚意识到，如果您在 <phase>compile</phase> 上执行上述运行，它会在您每次编译时更新文档；这意味着您不太可能在推送之前忘记更新它。 YMMV.

在 github 页中包含基于 pom.xml 的版本号？

Include pom.xml based version number in github pages?

github

maven

github-pages