READMEについて
README ファイルをリポジトリに追加して、プロジェクトに関する重要な情報を伝えることができます。 README は、リポジトリ ライセンス、引用ファイルと並んで、プロジェクトに期待されるものを伝え、コントリビューションを管理しやすくします。
プロジェクトのガイドラインを提供する方法の詳細については、「健全なコントリビューションを促すプロジェクトをセットアップする」を参照してください。
多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています:
- このプロジェクトが行うこと
- このプロジェクトが有益な理由
- このプロジェクトの使い始め方
- このプロジェクトに関するヘルプをどこで得るか
- このプロジェクトのメンテナンス者とコントリビューター
README ファイルをリポジトリの隠れ .github ルートまたは docs ディレクトリに置けば、GitHub AE はそれを認識して自動的に README をリポジトリへの訪問者に提示します。
リポジトリに複数の README ファイルが含まれている場合、表示されるファイルは、.github ディレクトリ、リポジトリのルート ディレクトリ、最後に docs ディレクトリの順に選択されます。
README ファイルの自動生成された目次
README ファイルなど、リポジトリの Markdown ファイルをレンダリングすると、GitHub AE によって、セクション見出しに基づいて目次が自動的に生成されます。 レンダリングされたページの左上にある メニューアイコンをクリックすると、README ファイルの目次を表示できます。
READMEファイルのセクションリンクとblobページ
セクションのヘッディング上にカーソルを移動させてリンクを表示させることにより、表示されたファイル中のセクションに対して直接リンクできます。
READMEファイル中の相対リンクと画像パス
表示されたファイル中で相対リンクと画像パスを定義して、読者がリポジトリ中の他のファイルにアクセスしやすくできます。
相対リンクは、現在のファイルに対する相対的なリンクです。 たとえば、リポジトリのルートに README ファイルがあり、docs/CONTRIBUTING.md に別のファイルがある場合、README の CONTRIBUTING.md への相対リンクは次のようになります。
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub AEは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 リンクのパスは、現在のファイルに対する相対パスになります。 / で始まるリンクは、リポジトリ ルートに対する相対パスです。 ./ や ../ のような相対リンクのオペランドをすべて使用できます。
相対リンクは、リポジトリをクローンするユーザにも扱いやすいです。 絶対リンクはリポジトリのクローンではうまく働かないかもしれません。リポジトリ内の他のファイルを参照するには、相対リンクを使うことをおすすめします。
Wiki
README には、開発者がプロジェクトを使用し、プロジェクトに貢献するために必要な情報のみを含めてください。 長いドキュメントは Wiki に最適です。 詳しくは、「ウィキについて」を参照してください。
参考資料
- ファイルをリポジトリに追加する
- 18F の「README を読み取り可能にする」