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