How to include github markdown files into maven site

Question

Github recommends that Markdown-formatted files like README.md, LICENCE.md or CONTRIBUTORS.md are created in the root of the project. On the other hand, those files would be valuable content for automatically generated maven sites.

What would be the best practice to include those files into the generated site report?

One Idea I had was copying them into src/site/markdown and removing them again after successful site generation (to avoid SCM pollution).

Answer 1

I solved this problem for the file README.md in a Git repository using the approach you outlined in your question, that is copying README.md from the root directory to ${baseDir}/src/site/markdown. I used maven-resources-plugin to copy the file. Instead of removing the copied file after the site is generated (to avoid SCM pollution), I added it to .gitignore as Bruno suggested.

A detailed description of the solution follows.

In section project.build.plugins of 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>

In .gitignore:

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

You can see the corresponding commit here.