READMEについて
リポジトリにREADMEファイルを追加して、そのプロジェクトがなぜ有益なのか、そのプロジェクトで何ができるか、そのプロジェクトをどのように使えるかを他者に伝えることができます。
ここには以下の内容があります:
README ファイルは、リポジトリのライセンス、コントリビューションガイドライン、行動規範と合わせて、プロジェクトへのコントリビューションに対する期待を示し、管理するのに役立ちます。
多くの場合、READMEはリポジトリへの訪問者が最初に目にするアイテムです。 通常、README ファイルには以下の情報が含まれています:
- このプロジェクトが行うこと
- このプロジェクトが有益な理由
- このプロジェクトの使い始め方
- このプロジェクトに関するヘルプをどこで得るか
- このプロジェクトのメンテナンス者とコントリビューター
README ファイルをリポジトリのルート、docs
、または隠れディレクトリ .github
に置けば、GitHub はそれを認識して自動的に README をリポジトリへの訪問者に提示します。
READMEファイルのセクションリンクとblobページ
多くのプロジェクトは、README の先頭にある目次を使ってユーザをファイル中のさまざまなセクションへ誘導します。 You can link directly to a section in a rendered file by hovering over the section heading to expose the link:
READMEファイル中の相対リンクと画像パス
表示されたファイル中で相対リンクと画像パスを定義して、読者がリポジトリ中の他のファイルにアクセスしやすくできます。
相対リンクは、現在のファイルに対する相対的なリンクです。 For example, if you have a README file in root of your repository, and you have another file in docs/CONTRIBUTING.md, the relative link to CONTRIBUTING.md in your README might look like this:
[このプロジェクトへのコントリビューションガイドライン](docs/CONTRIBUTING.md)
GitHubは相対リンクあるいは画像パスを、現在のブランチに基づいて変換するので、リンクやパスは常にうまく働きます。 ./
や../
といった相対リンクのオペランドはすべて利用できます。
相対リンクは、リポジトリをクローンするユーザにも扱いやすいです。 絶対リンクはリポジトリのクローンではうまく働かないかもしれません。リポジトリ内の他のファイルを参照するには、相対リンクを使うことをおすすめします。