Come includere i file markdown github nel sito Maven

Question

Github raccomanda che i file formattati con Markdown come README.md, LICENCE.md o CONTRIBUTORS.md vengano creati nella radice del progetto. D'altra parte, quei file sarebbero contenuti di valore per i siti maven generati automaticamente.

Quale sarebbe la migliore pratica per includere tali file nel report del sito generato?

Un'idea che avevo era di copiarli in src/site/markdown e rimuoverli di nuovo dopo la generazione del sito di successo (per evitare l'inquinamento di SCM).

Answer 1

I contributori devono essere inseriti nello pom. Il file di licenza dovrebbe essere parte del progetto solitamente LICENSE.txt come file di pari livello su pom.xml come suggerito da Apache. Il file README.txt è suggerito anche da Apache. README.md di solito è utile solo per GitHub per renderlo visibile durante la visualizzazione del repository.

Answer 2

ho risolto questo problema per il file README.md in un repository Git utilizzando l'approccio avete descritto nella sua domanda, che sta copiando README.md dalla directory principale per ${baseDir}/src/site/markdown. Ho usato maven-resources-plugin per copiare il file. Invece di rimuovere il file copiato dopo che il sito è stato generato (per evitare l'inquinamento di SCM), l'ho aggiunto a .gitignore come Bruno suggested.

Segue una descrizione dettagliata della soluzione.

Nella sezione project.build.plugins di 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 

Si può vedere la corrispondente commit here.