Skip to main content

READMEについて

リポジトリにREADMEファイルを追加して、そのプロジェクトがなぜ有益なのか、そのプロジェクトで何ができるか、そのプロジェクトをどのように使えるかを他者に伝えることができます。

READMEについて

README ファイルをリポジトリに追加して、プロジェクトに関する重要な情報を伝えることができます。 README は、リポジトリ ライセンス、引用ファイル、コントリビューション ガイドラインと並んで、プロジェクトに期待されるものを伝え、コントリビューションを管理しやすくします。

プロジェクトのガイドラインを提供する方法の詳細については、「健全なコントリビューションを促すプロジェクトをセットアップする」を参照してください。

多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています:

  • このプロジェクトが行うこと
  • このプロジェクトが有益な理由
  • このプロジェクトの使い始め方
  • このプロジェクトに関するヘルプをどこで得るか
  • このプロジェクトのメンテナンス者とコントリビューター

README ファイルをリポジトリの隠れ .github ルートまたは docs ディレクトリに置けば、GitHub Enterprise Server はそれを認識して自動的に README をリポジトリへの訪問者に提示します。

リポジトリに複数の README ファイルが含まれている場合、表示されるファイルは、.github ディレクトリ、リポジトリのルート ディレクトリ、最後に docs ディレクトリの順に選択されます。

README が GitHub で表示されると、500 KiB を超えるコンテンツは切り捨てられます。

自分のユーザ名と同じ名前のパブリックリポジトリのルートにREADMEファイルを追加したなら、そのREADMEは自動的に自分のプロフィールページに表示されます。 プロフィールのREADMEは、GitHub形式のMarkdownで編集し、プロフィール中にパーソナライズされたセクションを作成できます。 詳しくは、「プロフィールの README を管理する」を参照してください。

README ファイルの自動生成された目次

README ファイルなど、リポジトリの Markdown ファイルをレンダリングすると、GitHub Enterprise Server によって、セクション見出しに基づいて目次が自動的に生成されます。 レンダリングされたページの左上にある メニュー アイコンをクリックすると、README ファイルの目次を表示できます。

リポジトリの README のスクリーンショット。 左上隅に、リスト アイコンのラベルが付いたドロップダウン メニューが展開され、目次が表示されています。

見出しがある任意のセクションに直接リンクできます。 レンダリングされたファイルで自動的に生成されたアンカーを表示するには、セクション見出しにカーソルを合わせて アイコンを表示し、アイコンをクリックしてブラウザーにアンカーを表示します。

リポジトリの README のスクリーンショット。 セクション見出しの左側では、リンク アイコンが濃いオレンジ色の枠線で囲まれています。

セクション リンクの詳細については、「セクション リンク」を参照してください。

表示されたファイル中で相対リンクと画像パスを定義して、読者がリポジトリ中の他のファイルにアクセスしやすくできます。

相対リンクは、現在のファイルに対する相対的なリンクです。 たとえば、リポジトリのルートに README ファイルがあり、docs/CONTRIBUTING.md に別のファイルがある場合、README の CONTRIBUTING.md への相対リンクは次のようになります。

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub Enterprise Serverは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 リンクのパスは、現在のファイルに対する相対パスになります。 / で始まるリンクは、リポジトリ ルートに対する相対パスです。 ./../ のような相対リンクのオペランドをすべて使用できます。

リンク テキストは 1 行に記述する必要があります。 次の例は機能しません。

[Contribution 
guidelines for this project](docs/CONTRIBUTING.md)

相対リンクは、リポジトリをクローンするユーザにも扱いやすいです。 絶対リンクはリポジトリのクローンではうまく働かないかもしれません。リポジトリ内の他のファイルを参照するには、相対リンクを使うことをおすすめします。

Wiki

README には、開発者がプロジェクトを使用し、プロジェクトに貢献するために必要な情報のみを含めてください。 長いドキュメントは Wiki に最適です。 詳しくは、「ウィキについて」を参照してください。

参考資料