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

Question

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

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

我有一个想法是将它们复制到src/site/markdown并在成功生成网站后再次删除它们(以避免SCM污染).

Answer 1

我README.md使用你在问题中概述的方法解决了Git存储库中文件的这个问题,即README.md从根目录复制到${baseDir}/src/site/markdown.我曾经maven-resources-plugin复制过这个文件.在生成网站后(为了避免SCM污染),我没有删除复制的文件,而是将其添加到.gitignoreBruno 建议中.

下面是对该解决方案的详细描述.

在部分project.build.plugins的pom.xml:

<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，作为 Apache 建议的 pom.xml 文件的同级文件。Apache 也建议使用 README.txt。README.md 通常仅对 GitHub 在存储库显示期间呈现此内容有价值。