10

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

Hakan
  • 467
  • 4
  • 13
  • 1
    If you are using git you could add the copied files to the .gitignore to prevent these files being added to the source tree. I suppose other VCS have similar mechanisms. – Bruno Ranschaert Dec 02 '14 at 15:32

2 Answers2

7

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.

Community
  • 1
  • 1
Filip Bártek
  • 537
  • 6
  • 13
  • 3
    When you copy the file to `${basedir}/target/generated-site/markdown` which is also picked up by Maven, you don't need to add the file to `.gitignore`. The risk of editing the wrong copy is also reduced. – Jens Piegsa May 18 '18 at 23:10
0

The contributors should be put into the pom. The license file should be part of the project usually LICENSE.txt as sibling to pom.xml file as Apache suggested. The README.txt is suggested by Apache as well. README.md is usually only valuable for GitHub to render this during the display of the repository.

khmarbaise
  • 81,692
  • 23
  • 160
  • 199
  • 3
    I am aware of the maven conventions. I just want to avoid keeping double copies of relevant information, adhering to the DRY (don't-repeat-yourself) principle. – Hakan Dec 06 '12 at 17:50