mavenサイトにgithubマークダウンファイルを含める方法

Question

Githubは、プロジェクトのルートにREADME.md、LICENCE.md、CONTRIBUTORS.mdなどのMarkdown形式のファイルを作成することを推奨しています。一方、これらのファイルは、自動的に生成されたMavenサイトの貴重なコンテンツとなります。

これらのファイルを生成されたサイトレポートに含めるのがベストプラクティスですか？

私が持っていた1つのアイデアは、src/site/markdownにそれらをコピーし、サイト生成が成功した後に（SCM汚染を避けるために）それらを再び削除することでした。

Answer 1

投稿者はpomに入れてください。ライセンスファイルはプロジェクトの一部である必要があります。通常、LICENSE.txtはApacheが示唆しているように、pom.xmlファイルの兄弟として扱われます。 README.txtはApacheでも提案されています。 README.mdは通常、GitHubがリポジトリの表示中にこれをレンダリングするためにのみ有益です。

Answer 2

私はGitリポジトリのファイルREADME.mdに対して、あなたの質問で概説したアプローチ、つまりREADME.mdをルートディレクトリからにコピーしてこの問題を解決しました。私はmaven-resources-pluginを使ってファイルをコピーしました。 SCMの汚染を避けるために、サイトが生成された後にコピーされたファイルを削除する代わりに、.gitignoreにBruno suggestedと追加しました。

解決策の詳細な説明が続きます。 pom.xmlのセクションproject.build.pluginsで

：

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

.gitignoreで：

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

あなたはhereをコミット対応見ることができます。