READMEの書き方

Git Hubでリポジトリをダウンロードしたときに、「README.md」というファイルを見たことはありませんか？

README（リードミー）とはリポジトリに訪れた人に、このプロジェクトが何なのかをわかりやすく伝えるための説明書のようなものです。

つまり、自分がソースコードを上げる側になった場合、READMEをきちんと書く（マークダウン形式）必要があります。

Webエンジニア初心者の人は自分のコードを Git Hub にあげるまでは、よくやります。

しかし、README までちゃんと書いていない人は結構多いですよね。

今回はGit Hub初心者に向けて、READMEの書き方についてエントリーします。

 

手順

 

マークダウンの書き方

マークダウンとは普通のテキストファイルを、ちょっとした法則にならって書くだけで、HTMLマークアップせずに、自動的にHTMLコードとして変換して出力してくれるというもの。

READMEファイルは、基本的にこのマークダウン記法でリポジトリについての説明を書きます。

 

見出し

シャープ（#） + 半角スペース。

行頭の#の個数でH1～H6を表します。

# H1見出し
## H２見出し
### H3見出し

 

段落

空行をあける。

１段落目
（空行をはさむ）
２段落目

 

強調

アスタリスク（*）またはアンダーバー（_）で囲む

*強調* または _強調_

**強調** または __強い強調__

 

リスト

リストの記述は３種類あります。

１）行頭にアスタリスク（*）+ 半角スペース
２）行頭にハイフン（-）+ 半角スペース
３）行頭にプラス（+）+ 半角スペース

ネストはタブで表現します。

* リスト１
    * リスト1_1
    * リスト1_2
* リスト２
* リスト３

 
番号つきリスト → 番号ピリオド（1.）+ 半角スペース

番号つきリストも同様にネストはタブで表現します。

1. 順番つきリスト
2. 順番つきリスト
3. 順番つきリスト

 

リンク

自動リンク

アングルブラケット<>でURLを囲う。メアドでも可能。

<http://example.com>
<example@example.com>

 

通常のインライン記法

[リンクのテキスト](リンクのアドレス "リンクのタイトル")

# 例
[Google](https://www.google.co.jp/)

 

画像

先頭にビックリマーク

![Alt text](/path/to/img.jpg)

 

コードの挿入

```（バッククオート３つ）でコードをくくる。

※クォーテーション ' ではない。

```
function hello(){
   return "hello world!";
}
```

 

マークダウンにHTMLを埋め込む

マークダウンはHTML直接書き込みがいけます。

<p align="center">
<img src="https://raw.githubusercontent.com/honjou/docker_practice/images/logo.png">
</p>

 

Git Hubに画像をアップロード

１．空のブランチを作る

git checkout --orphan images
git rm -rf .

 

２．そこに画像を置きます

 

３．リモートにプッシュ

git add logo.png
git commit -m "Add logo image"
git push origin images

 

4．画像のパスをメモします

Git Hub のサイトにアクセスして画像がちゃんとアップされたか確認してみましょう。

ブランチは下図のように "images" に変更します。

# 画像は以下のようなURLで参照できます
https://raw.githubusercontent.com/ユーザ名/リポジトリ名/images/logo.png

# 実例
https://raw.githubusercontent.com/honjou/scraping/images/logo.png

 

あとは、マークダウン記法で画像を表示させてOKです。

 

5．元のブランチにもどります

git checkout master

 

削除したデータはここで戻ってきます。

 

READMEのテンプレート

REAMEに盛り込む内容は基本的には以下で十分かと思います。

ただ、個人的にはREADMEはできるだけシンプルにしたほうがいいと思っています。

ちょっと項目が多いかな？と思う人はいくつか省略してもいいかもしれません。

最初にロゴ・アイキャッチ画像などを表示

# リポジトリ名

概要を記述する


## デモ

![デモ](https://image-url.gif)


## 使い方

DEMOの実行方法など、"Webアプリ"の基本的な使い方を説明

1. 使い方
2. 使い方
3. 使い方


## 環境

* 要件
* 要件
* 要件


## 注意事項

注意点などがあれば書く


## 文責

作成情報を列挙する

* 作成者
* 所属
* E-mail
* [@twitter_username](https://twitter.com/twitter_username)


## ライセンス

ライセンスを明示する

"リポジトリ名" is under [MIT license](https://en.wikipedia.org/wiki/MIT_License).


## 参考文献

参考にした情報源（サイト・論文）などの情報、リンク

 

実際に書いてみた

honjou / scraping｜Git Hub

以前、Webスクレイピングの記事を書いて、コードをGitHubにあげました。

ただ、READMEは何も書いてなかったので、今回、リポジトリについての説明書を書いてみました。

 

Before

 

After

 

Webエンジニア初心者の方にとってREADMEファイルは軽視されがちです。（※そこまで気が回らない？）

しかし、少し手をいれるだけで多くの人に使ってもらえたり、プルリクエストしてくれる人が出てきます。

今まで軽視していた人はこの機会に是非、READMEファイルを書いてみてください。

以上です。

 

 

-周辺知識