Как включить файлы разметки github на сайт 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), я добавил его в .gitignore как предложил Бруно.

Подробное описание решения приведено ниже.

В разделе 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

Авторы должны быть помещены в пом. Файл лицензии должен быть частью проекта, как правило, LICENSE.txt, как одноименный файл pom.xml, как предложил Apache. README.txt также предлагается Apache. README.md обычно полезен только для GitHub, чтобы отобразить это во время отображения хранилища.