READMEについて
README ファイルをリポジトリに追加して、プロジェクトに関する重要な情報を伝えることができます。 README は、リポジトリライセンス 、コントリビューションガイドライン、行動規範 とともに、プロジェクトへの要望を伝え、コントリビューションの管理を支援します。
プロジェクトのガイドラインの提供方法の詳細については、「プロジェクトに行動規範を追加する」および 「健全なコントリビューションのためのプロジェクトの設定」を参照してください。
多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています:
- このプロジェクトが行うこと
- このプロジェクトが有益な理由
- このプロジェクトの使い始め方
- このプロジェクトに関するヘルプをどこで得るか
- このプロジェクトのメンテナンス者とコントリビューター
README ファイルをリポジトリのルート、docs、または隠れディレクトリ .github に置けば、GitHub はそれを認識して自動的に README をリポジトリへの訪問者に提示します。
自分のユーザ名と同じ名前のパブリックリポジトリのルートにREADMEファイルを追加したなら、そのREADMEは自動的に自分のプロフィールページに表示されます。 プロフィールのREADMEは、GitHub形式のMarkdownで編集し、プロフィール中にパーソナライズされたセクションを作成できます。 詳しい情報については、「プロフィール README の管理」を参照してください。
Auto-generated table of contents for README files
For the rendered view of any Markdown file in a repository, including README files, GitHub 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.
The auto-generated table of contents is enabled by default for all Markdown files in a repository, but you can disable this feature for your repository.
- GitHubで、リポジトリのメインページにアクセスしてください。
- リポジトリ名の下で Settings（設定）をクリックしてください。
- Under "Features", deselect Table of contents.
READMEファイルのセクションリンクとblobページ
セクションのヘッディング上にカーソルを移動させてリンクを表示させることにより、表示されたファイル中のセクションに対して直接リンクできます。
READMEファイル中の相対リンクと画像パス
表示されたファイル中で相対リンクと画像パスを定義して、読者がリポジトリ中の他のファイルにアクセスしやすくできます。
相対リンクは、現在のファイルに対する相対的なリンクです。 たとえばREADMEファイルをリポジトリのルートに置いていて、別のファイルをdocs/CONTRIBUTING.mdに置いているなら、READMeファイル中のCONTRIBUTING.mdへの相対リンクは以下のようになります。
[このプロジェクトへのコントリビューションガイドライン](docs/CONTRIBUTING.md)
GitHubは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 ./や../といった相対リンクのオペランドはすべて利用できます。
相対リンクは、リポジトリをクローンするユーザにも扱いやすいです。 絶対リンクはリポジトリのクローンではうまく働かないかもしれません。リポジトリ内の他のファイルを参照するには、相対リンクを使うことをおすすめします。