How to enable github markup files in maven site

Question

Github recommends that files in the Markdown format, such as README.md, LICENCE.md or CONTRIBUTORS.md, be created at the root of the project. On the other hand, these files will be valuable content for automatically created maven sites.

What would be the best practice for including these files in the generated site report?

One idea I had was to copy them to src / site / markdown and delete them again after the site was successfully created (to avoid SCM pollution).

Answer 1

I solved this problem for the README.md file in the Git repository using the approach described in your question, which copies README.md from the root directory to ${baseDir}/src/site/markdown . I used maven-resources-plugin to copy the file. Instead of deleting the copied file after the site was created (to avoid SCM pollution) I added it to .gitignore as suggested by Bruno .

The following is a detailed description of the solution.

In the 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 .

Answer 2

Participants must be placed in pom . The license file should be part of the project usually LICENSE.txt as sibling for the pom.xml file, as suggested by Apache. README.txt is also offered by Apache. README.md is usually only useful for GitHub to render this while displaying the repository.