Skip to main content

READMEについて

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

READMEについて

README ファイルをリポジトリに追加して、プロジェクトに関する重要な情報を伝えることができます。 A README, along with a repository license, citation file and contribution guidelines, communicates expectations for your project and helps you manage contributions.

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

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

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

If you put your README file in your repository's hidden .github, root, or docs directory, GitHub Enterprise Server will recognize and automatically surface your README to repository visitors.

If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

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

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

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

Auto-generated table of contents for README files

For the rendered view of any Markdown file in a repository, including README files, GitHub Enterprise Server will automatically generate a table of contents based on section headings. You can view the table of contents for a README file by clicking the menu icon at the top left of the rendered page.

README with automatically generated TOC

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

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

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

相対リンクは、現在のファイルに対する相対的なリンクです。 たとえばREADMEファイルをリポジトリのルートに置いていて、別のファイルをdocs/CONTRIBUTING.mdに置いているなら、READMeファイル中のCONTRIBUTING.mdへの相対リンクは以下のようになります。

[このプロジェクトへのコントリビューションガイドライン](docs/CONTRIBUTING.md)

GitHub Enterprise Serverは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 The path of the link will be relative to the current file. Links starting with / will be relative to the repository root. ./../といった相対リンクのオペランドはすべて利用できます。

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

Wiki

A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis. 詳細は「ウィキについて」を参照してください。

参考リンク