Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となります: 2023-01-18. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください

READMEについて

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

READMEについて

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

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

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

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

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

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

github/scientistリポジトリのメインページとそのREADMEファイル

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

ユーザ名/ユーザ名リポジトリの README ファイル

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

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

自動的に生成された TOC を含む README

セクションのヘッディング上にカーソルを移動させてリンクを表示させることにより、表示されたファイル中のセクションに対して直接リンクできます。

github/scientistリポジトリのREADMEファイル内のセクションリンク

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

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

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

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

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

Wiki

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

参考資料