如何将 github markdown 文件包含在 maven 站点中

Question

Github建议在项目的根目录中创建Markdown格式的文件，如 README.md，LICENCE.md 或 CONTRIBUTORS.md。另一方面，这些文件对于自动生成的 maven 站点来说将是有价值的内容。

将这些文件包含在生成的站点报告中的最佳做法是什么？

我的一个想法是将它们复制到 src/site/markdown 中，并在成功生成站点后再次删除它们（以避免 SCM 污染）。

Answer 1

我使用您在问题中概述的方法为Git存储库中的文件README.md解决了此问题，即将README.md从根目录复制到${baseDir}/src/site/markdown。我用maven-resources-plugin复制文件。我没有在网站生成后删除复制的文件（以避免 SCM 污染），而是按照 Bruno 的建议将其添加到.gitignore。

解决方案的详细说明如下。

在pom.xml的第project.build.plugins节中：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <!-- Copy the readme file to the site source files so that a page is generated from it. -->
            <id>copy-readme</id>
            <phase>pre-site</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${basedir}/src/site/markdown</outputDirectory>
                <resources>
                    <resource>
                        <directory>${basedir}</directory>
                        <includes>
                            <include>README.md</include>
                        </includes>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

在.gitignore：

# Copied from root to site source files by maven-resources-plugin
/src/site/markdown/README.md

您可以在此处查看相应的提交。

Answer 2

贡献者应该被放入pom中。许可证文件应该是项目的一部分，通常是 LICENSE.txt作为 Pom.xml 文件的兄弟，正如 Apache 建议的那样。README.txt也是由Apache建议的。README.md 通常只对 GitHub 在存储库显示期间呈现此内容有价值。