READMEについて
リポジトリにREADMEファイルを追加して、そのプロジェクトがなぜ有益なのか、そのプロジェクトで何ができるか、そのプロジェクトをどのように使えるかを他者に伝えることができます。
README ファイルは、リポジトリのライセンスおよびコントリビューションガイドラインと合わせて、プロジェクトへのコントリビューションに対する期待を示し、管理するのに役立ちます。
多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています:
- このプロジェクトが行うこと
- このプロジェクトが有益な理由
- このプロジェクトの使い始め方
- このプロジェクトに関するヘルプをどこで得るか
- このプロジェクトのメンテナンス者とコントリビューター
README ファイルをリポジトリのルート、docs、または隠れディレクトリ .github に置けば、GitHub Enterprise はそれを認識して自動的に README をリポジトリへの訪問者に提示します。
READMEファイルのセクションリンクとblobページ
多くのプロジェクトは、README の先頭にある目次を使ってユーザをファイル中のさまざまなセクションへ誘導します。 セクションのヘッディングにカーソルを置いてリンクを表示させれば、表示されたファイル中のセクションに直接リンクできます。
READMEファイル中の相対リンクと画像パス
表示されたファイル中に相対リンクや画像パスを定義すると、読者はリポジトリ中の他のファイルにアクセスしやすくなります。
相対リンクは、現在のファイルに対して相対的なリンクです。たとえば README ファイルがリポジトリのルートにあり、他のファイルを docs/CONTRIBUTING.md に持っている場合は、README 内での CONTRIBUTING.md への相対リンクは以下のようになります:
[このプロジェクトへのコントリビューションガイドライン](docs/CONTRIBUTING.md)
GitHub Enterprise は、自動的に相対リンクあるいは画像パスを現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。./ や ../ といったすべての相対リンクのオペランドが利用できます。
相対リンクは、リポジトリをクローンするユーザにとっては使いやすいものです。絶対リンクはリポジトリのクローンではうまく働かない場合があります。リポジトリ内の他のファイルを参照する際には、相対リンクを使うことをおすすめします。