GitHubのREADMEを書く為のいろは

3625 ワード
GitHub Readme GitHub テキストリンク

はじめに

綺麗なREADMEを書くためにはどうすれば良いのか、自分なりのルールを作ったので記事にまとめたいと思います。

使用するGitホスティングサービス

  • GitHub

まず初めに

GitHubでリモートリポジトリを作成する場合、GitHubがデフォルトとしてREADMEのテンプレートを用意してくれていますので、それを利用するようにしましょう。
以下はPHPのフレームワークであるLaravelを使い、MITライセンスでプロジェクトを公開する場合の設定のサンプルです。

書いた方が良い項目

  • バッジ一覧
    • よく見かける↓です。詳細は下記を参照下さい
  • Introduction
    • そのプロジェクトの簡単な紹介文を1行程度で簡単にまとめます。
  • Demonstration
    • そのプロジェクトの簡単なデモ画像やgif動画を貼り、ひと目でどういうプロジェクトなのかが分かるようにします
  • Features
    • そのプロジェクトの特徴、このプロジェクトを使うことでどういった目的を叶えることができるのかを詳細に記載します
  • Requirements
    • そのプロジェクトの必要要件。必要な言語やライブラリのバージョンなどを記載します
  • Installation
    • そのプロジェクトがパッケージとして公開されている場合には、インストール方法、インストールコマンドを記載します
  • Usage
    • そのプロジェクトの使い方を箇条書きで記載します。なお、詳細な使い方については別項目やwikiなどに記載します
  • Sample
    • そのプロジェクトを使うためのサンプルコードなど、プロジェクトを使う上での詳細なイメージや使い方を記載します
  • Contributing
    • プロジェクトへの貢献の仕方についてのリンクを記載する
      • CONTRIBUTING.mdというファイルを用意し、そこにプロジェクト貢献のためのルールを記載し、そのリンクをREADMEには記載します
  • License
    • ライセンスについて記載します
This package is open-sourced software licensed under the [MIT license](https://choosealicense.com/licenses/mit/)

まとめると...

# Hogehoge Project
[![Laravel 6|7|8](https://img.shields.io/badge/Laravel-6|7|8-orange.svg)](http://laravel.com)
[![License](https://poser.pugx.org/stepupdream/blueprint/license)](//packagist.org/packages/stepupdream/blueprint)

## Introduction

## Demonstration

## Features

## Requirements 

## Installation 

## Usage

## Sample

## Contributing

## License

The Blueprint is open-sourced software licensed under the [MIT license](https://choosealicense.com/licenses/mit/)

READMEに使うバッジについて

以下で作ることができます。URLを自分のREADMEに貼り付けるだけで見た目の綺麗なREADMEにすることができます。
※数値部分の値は反映に少し時間がかかる場合があるようです

その他、各種サービスに関するバッジについてはそれぞれのサービス内で配布されていますのでそれを利用します。
※GitHub Actionsのバッジであれば、GitHub Actionsのページ内でリンクが提供されています

GitHub Actionsのバッジについて

こちらからリンクを取得することができます

参考