Question

我在GitHub上有一个基于Java Maven的project，我保留documentation on GitHub Pages。

在两个地方，我指的是我的maven项目的版本号。目前，我手动使用版本号手动更新index.md和readme.md（在一个页面上多次）。

版本号是否可以包含单一来源？

其中一个：

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

建议表示赞赏

Answer 1

有一种方法可以使用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 ，因为任何运行maven的构建管道也会更新该文档但不会提交（除非您这样做了）它）。

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

Answer 2

问题是这些文件是在两个不同的上下文中访问的：README.md只能在GitHub本身或repo的副本中读取。在Jekyll处理之后，index.md文件将转换为index.html文件并在您的网页上查看。

小解决方案：在页面顶部定义它。

同样，问题在于README.md未处理成HTML，因此将其添加到前端内容并不会将其神奇地添加到内容中。

中等解决方案：为文档定义一次（挑战：/ doc文档从readme.md运行不同（？））

您仍然遇到README.md未处理的问题。这只是基本文本。

最佳解决方案：从pom.xml
中读取它

除非您在Jekyll网站中发布pom.xml个帖子，否则无法从GitHub页面执行此操作。这几乎绝对不是你想要做的。

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

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

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

2 个答案: