How to include github markdown files into maven site

github, markdown, maven, maven-site-plugin

Solution

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.

Problem

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).

Original source