Markdownの書き方入門:README.mdを一から書いて学ぶ表示の仕組みとつまずく点

Markdownの書き方入門:README.mdを一から書いて学ぶ表示の仕組みとつまずく点
hr
記事内に商品プロモーションを含む場合があります

GitHub でリポジトリを開くと、ファイルの一覧の下に説明書のようなページが表示されます。これが README.md で、Markdown(マークダウン)という書き方で書かれています。この記事では、架空の小さなツールの README を一から書きながら、README に何を書けばよいか、書いた Markdown がどう表示されるか、GitHub ならではの表示の違い、初心者がつまずきやすい点と直し方を説明します。

見出し・太字・リストなどの記号の一覧は、「Markdownプレビュー」のページに「Markdown の書き方早見表」としてまとめています。この記事では記号の一覧はくり返さず、「README を実際に書く」ことに絞ります。

表示の決まりは、CommonMark の仕様(CommonMark Spec 0.31.2)、GitHub の仕様(GitHub Flavored Markdown Spec 0.29-gfm)、GitHub Docs の「Basic writing and formatting syntax」「About READMEs」の原文で確認しました(2026 年 10 月 18 日)。例の Markdown は、Markdownプレビューのツールに入れて、仕様どおりの HTML になることも確かめています。

README とは?

README は「最初に読んでね」という意味の名前のファイルで、そのリポジトリ(ソースコードの置き場所)が何なのか、どう使うのかを説明します。GitHub では、README を置くとリポジトリのトップページに自動で表示されます。拡張子を .md にすると Markdown として解釈され、見出しや表、コードブロックが整った形で表示されます。

GitHub Docs によると、GitHub が README を探す場所は次の 3 か所で、複数あるときはこの順に優先されます。

  1. 隠しフォルダーの .github
  2. リポジトリの一番上のフォルダー(ルート)
  3. docs フォルダー

ふつうはルートに置けば十分です。また、表示される README は 500 KiB までで、それを超える部分は切り捨てられます。説明が長くなるときは、別のファイルに分けてリンクする方法を後で紹介します。

README に書くべき項目

GitHub Docs では、README に書く内容として「何をするプロジェクトか」「なぜ役に立つのか」「どう使い始めるのか」「どこで助けを得られるか」「誰が管理・貢献しているか」の 5 つが挙げられています。これを小さなツールに当てはめると、次の項目になります。上から順に並べると、初めて見た人が迷わずに読めます。

項目書く内容なくて困ること
名前と 1〜2 行の説明何をするものか、どんなときに使うか読み手が自分に関係あるか判断できない
主な機能できることを 3〜5 個の箇条書きで全部読まないと何ができるか分からない
必要なもの言語のバージョン、OS、必要なライブラリ動かない原因が環境なのか分からない
インストールそのままコピーして実行できるコマンド手順を推測することになり、間違える
使い方いちばん基本の実行例と、その結果動かしてみるまで結果が想像できない
オプション・設定指定できる値と既定値を表でソースコードを読まないと分からない
開発に参加する・問い合わせ不具合の報告先、参加のルールどこに連絡すればよいか分からない
ライセンス利用条件(MIT License など)使ってよいのか判断できない

すべてが必要なわけではありません。自分用の小さなスクリプトなら「説明・必要なもの・使い方」の 3 つだけでも、半年後の自分にとって十分役に立ちます。

実例:小さなツールの README を一から書く

題材にするツール

題材として、フォルダーの中のファイルの行数を数える、Python の小さなツール「linecount」を作りました(この記事のための架空のツールで、公開はしていません)。中身は次の 15 行です。

import argparse
from pathlib import Path

parser = argparse.ArgumentParser(description="フォルダー内のファイルの行数を数えます。")
parser.add_argument("folder", help="調べるフォルダー")
parser.add_argument("--ext", default=".py", help="対象の拡張子(既定値: .py)")
parser.add_argument("--encoding", default="utf-8", help="ファイルの文字コード(既定値: utf-8)")
args = parser.parse_args()

total = 0
for path in sorted(Path(args.folder).rglob("*" + args.ext)):
    count = len(path.read_text(encoding=args.encoding).splitlines())
    total += count
    print(f"{count:5}  {path.as_posix()}")
print(f"{total:5}  合計")

sample フォルダーに main.py(1 行)と sub\calc.py(6 行)を置き、Windows 11 の PowerShell で実行すると、次のように表示されました(Python 3.12)。

py linecount.py sample
    1  sample/main.py
    6  sample/sub/calc.py
    7  合計

完成した README.md

このツールの README.md を、先ほどの項目に沿って書いたものが次です。メモ帳や VS Code などで、文字コード UTF-8 のテキストファイルとして、リポジトリのルートに README.md という名前で保存します。

# linecount

フォルダーの中にあるファイルの行数を、ファイルごとと合計で表示するコマンドです。
「このプロジェクトは何行あるのか」をすぐに確かめたいときに使います。

![実行したときの画面](docs/screenshot.png)

## 主な機能

- サブフォルダーの中まで調べて、ファイルごとの行数と合計を表示する
- 対象の拡張子を選べる(既定値は `.py`)
- 文字コードを指定できる(既定値は UTF-8)

## 必要なもの

- Python 3(3.12 で動作を確認)
- 追加のライブラリは不要

## インストール

```bash
git clone https://github.com/your-name/linecount.git
cd linecount
```

## 使い方

調べたいフォルダーを指定して実行します。

```bash
python linecount.py sample
```

実行結果の例:

```text
    1  sample/main.py
    6  sample/sub/calc.py
    7  合計
```

### オプション

| オプション | 説明 | 既定値 |
| --- | --- | --- |
| `--ext` | 対象の拡張子 | `.py` |
| `--encoding` | ファイルの文字コード | `utf-8` |
| `-h` | 使い方を表示する | なし |

## 今後の予定

- [x] 拡張子の指定
- [ ] 空行を数えないオプション
- [ ] 結果を CSV で出力する

## 開発に参加する

不具合の報告や要望は、Issue で受け付けています。
くわしくは [CONTRIBUTING.md](CONTRIBUTING.md) を読んでください。

## ライセンス

[MIT License](LICENSE)

your-name の部分は、自分の GitHub のユーザー名に置き換えます。そのままコピーして、Markdownプレビューに貼ると、表示を確かめられます。

それぞれの部分がどう表示されるか

Markdown は、表示されるときに HTML(Web ページの部品)に変換されます。この README の各部分が、どの部品になるかをまとめました。HTML の列は、Markdownプレビューの「生成された HTML を表示する」で確かめた結果で、CommonMark・GFM の仕様の例とも一致しています。

README の部分変換される HTML表示
# linecounth1一番大きな見出し。README の先頭に 1 つだけ置く
説明の 2 行p(1 つの段落)2 行は改行されず、1 つの段落としてつながる(理由は後述)
![実行したときの画面](docs/screenshot.png)imgリポジトリの中の画像を表示する
## 主な機能、### オプションh2、h3章と、その中の小見出し
- で始まる行ul と li箇条書き
```bash 〜 ```pre と codeコードブロック。中の文字は記号の意味を持たず、書いたとおり表示される
| と --- の行table3 列 × 3 行の表(1 行目は見出しの行)
- [x]、- [ ]li の中のチェックボックスチェック済み・未チェックの項目
[CONTRIBUTING.md](CONTRIBUTING.md)a同じリポジトリの中のファイルへのリンク

書くときのポイントは次のとおりです。

  • 見出しの階層を飛ばさない:# はタイトルの 1 回だけにして、章は ##、章の中の小見出しは ### にします。GitHub は 2 つ以上の見出しがあると目次を自動で作るので、階層がそろっていると目次も読みやすくなります。
  • コードブロックには言語名を付ける:```bash のように書くと、GitHub などでは言語に合わせた色分けで表示されます。実行結果のように色分けしたくないものは ```text にするか、言語名を書きません。
  • コマンドは 1 行ずつ、そのまま実行できる形にする:$ などのプロンプト記号を付けると、コピーしたときに一緒に貼られてエラーになります。
  • 表の縦線はそろえなくてよい:GitHub Docs にも「セルの幅はそろっていなくてよい」とあります。見出しの下の行は、列ごとに ---(3 つ以上のハイフン)を書きます。

GitHub での表示の違いを確認する

GitHub の Markdown は、CommonMark に表・タスクリスト・取り消し線などを加えた GFM(GitHub Flavored Markdown)です。ほかのツールで書いた Markdown を GitHub に置くと、表示が少し変わる部分があります。GitHub Docs の原文で確認した内容をまとめます。

書き方GitHub での表示注意すること
改行(Enter を 1 回).md ファイルでは改行されない。Issue・プルリクエスト・ディスカッションでは改行される.md で改行したいときは、行末に半角スペース 2 つか「\」、または <br> タグ
表表として表示表の前に空の行が必要。セル内の「|」は「\|」と書く
タスクリストチェックボックスとして表示項目の先頭が「(」のときは「\(」とエスケープする
相対リンク表示中のブランチに合わせて、リポジトリ内のファイルへのリンクに変換される「/」で始めるとリポジトリのルートからの位置になる。リンクの文字は 1 行に収める
画像リポジトリ内の画像も、外部の画像も表示リポジトリ内の画像は相対パスで書く。説明の文字(代替テキスト)を書く
見出し見出しごとにリンク先(アンカー)が自動で作られ、目次も自動で作られる同じ名前の見出しには、末尾に「-1」「-2」が付く

改行:.md ファイルと Issue で動きが違う

いちばん戸惑いやすいのが改行です。GitHub Docs では、Issue・プルリクエスト・ディスカッションに書いた文章は改行が自動で反映される一方、.md ファイルでは同じ文章が 1 行につながって表示されると説明されています。README の説明の 2 行がつながって表示されるのはこのためです。Issue で書いたときと同じ感覚で README を書くと、「改行したはずなのに 1 行になった」と感じます。直し方は、後の「つまずきやすい点」で説明します。

Markdownプレビューでは、オプションの「改行をそのまま改行として表示する」にチェックを入れると Issue と同じ表示に、外すと .md ファイルと同じ表示になります。

相対リンク:リポジトリの中のファイルを指す

README から同じリポジトリの中のファイルへリンクするときは、https://github.com/... から始まる URL(絶対リンク)ではなく、README からの位置で書く「相対リンク」にします。GitHub Docs でも相対リンクがすすめられていて、理由として、リポジトリを手元にコピー(クローン)した人にとっても使いやすいことが挙げられています。

書き方リンク先
[説明](CONTRIBUTING.md)README と同じフォルダーの CONTRIBUTING.md
[説明](docs/CONTRIBUTING.md)docs フォルダーの中の CONTRIBUTING.md
[説明](../README.md)1 つ上のフォルダーの README.md(docs の中の .md から戻るときなど)
[説明](/docs/setup.md)リポジトリのルートから見た docs/setup.md

GitHub は、相対リンクを表示中のブランチに合わせて変換します。たとえば develop ブランチの README を見ているときは、develop ブランチの CONTRIBUTING.md が開きます。絶対リンクで main ブランチを指していると、ほかのブランチで見たときに古い内容が開いてしまいます。

画像:リポジトリに入れて相対パスで指す

README の ![実行したときの画面](docs/screenshot.png) は、リポジトリの docs フォルダーに screenshot.png を入れておくと、その画像を表示します。[ ] の中の文字は代替テキストといい、画像が表示できないときや、画面の読み上げソフトで読まれる説明です。GitHub Docs でも、リポジトリの中の画像は相対パスで書くよう案内されています。なお、非公開(プライベート)のリポジトリの画像は、そのリポジトリを読む権限がある人にだけ表示されます。

Markdownプレビューは、外部と通信しない安全な作りにしているため、画像やリポジトリ内への相対リンクは読み込まずに文字で表示します。画像やリンクの見た目は、GitHub に置いてから確かめてください。

見出しへのリンクと目次

GitHub では、見出しごとにリンク先が自動で作られます。英語の見出しの場合、GitHub Docs に書かれている規則は「小文字にする」「スペースはハイフン(-)にする」「それ以外の空白と記号は取り除く」です。たとえば ## Getting Started へのリンクは [始め方](#getting-started) と書けます。日本語の見出しの場合は、GitHub で見出しにマウスを合わせると出るリンクのアイコンを押し、ブラウザーのアドレス欄から # 以降をコピーするのが確実です。

つまずきやすい点と直し方

ここからは、README を書いていてよく起きる「思ったように表示されない」例です。どれも Markdownプレビューに入れて、CommonMark・GFM の仕様の例と同じ結果になることを確かめています。

改行したのに 1 行につながる

Markdown では、Enter を 1 回押しただけの改行は「ソフト改行」と呼ばれ、表示では前の行とつながって 1 つの段落になります。目的に合わせて、次の 3 つを使い分けます。

書き方変換結果使いどころ
行の間に空の行を入れる別々の段落(p が 2 つ)話題が変わるとき。いちばん確実
行末に半角スペースを 2 つ以上同じ段落の中で改行(br)住所や手順の区切りなど。スペースが見えないので消されやすい
行末に「\」同じ段落の中で改行(br)改行していることが目で見て分かる

行末のスペースは、エディターの「保存時に行末の空白を削除する」設定で消えてしまうことがあります。消えても困らないよう、段落を分けるか「\」を使うのがおすすめです。なお、CommonMark の仕様では、段落や見出しの最後の行に付けたスペース 2 つや「\」は改行になりません(最後の行のスペースは取り除かれ、「\」はそのまま文字として表示されます)。

リストが入れ子にならない(スペースの数)

箇条書きの中に箇条書きを入れる(入れ子にする)ときは、子の行の先頭にスペースを入れます。必要なスペースの数は「親の項目の文字が始まる位置」で決まります。- は記号 1 文字とスペース 1 つなので 2 つ、1. は 3 文字なので 3 つです。足りないと、入れ子にならず同じ階層の項目になります。

- 親
 - 子(スペース 1 つ:入れ子にならない)

- 親
  - 子(スペース 2 つ:入れ子になる)

番号付きリストでは、スペース 2 つでは足りません。次の 1 つ目は、番号付きリストと箇条書きが別々に並び、2 つ目だけが入れ子になります。

1. 親
  - 子(スペース 2 つ:入れ子にならない)

1. 親
   - 子(スペース 3 つ:入れ子になる)

CommonMark の仕様でも、10) のように番号が 2 けたになると記号が広くなるため、スペースが 4 つ必要な例が示されています。GitHub Docs の説明も同じで、「子の記号が、上の項目の文字の 1 文字目の真下に来るまでスペースを入れる」と書かれています。迷ったら、エディターで親の文字の位置に子の記号の縦の位置をそろえてください。

コードブロックの中に “` を書きたい

Markdown の書き方そのものを README で説明したいときなど、コードブロックの中に ``` を書くと、そこでコードブロックが終わってしまいます。たとえば次のように書くと、2 行目の ```bash は中身として扱われますが、4 行目の ``` で外側のブロックが閉じ、最後の ``` から新しいコードブロックが始まります。閉じる行がないコードブロックはファイルの最後まで続くので、その下の文章がすべてコードとして表示されてしまいます。

```markdown
```bash
ls
```
```

直し方は、外側のバッククォート(`)を内側より多くすることです。CommonMark の仕様では、閉じる行は開いた行と同じ記号で、同じ数以上でなければなりません。外側を 4 つにすると、内側の 3 つは中身として表示されます。

````markdown
```bash
ls
```
````

外側を ~~~(チルダ 3 つ)にする方法もあります。チルダで開いたブロックは、バッククォートの行では閉じません。

インラインコードの中にバッククォートを書きたい

文の中のコード(インラインコード)も同じ考え方です。中にバッククォートを 1 つ含めたいときは、外側を 2 つで囲みます。開く側と閉じる側は同じ数でなければなりません。

`` a`b ``

これは a`b と表示されます。囲みの内側の両端にスペースを 1 つずつ入れているのは、中身がバッククォートで始まったり終わったりするときに、外側とくっつかないようにするためです。両端にスペースがあるときは、表示ではそれぞれ 1 つずつ取り除かれます。

表の中で | を使いたい

表の中に「a または b」を表す a | b のような文字を書くと、| が列の区切りとみなされます。GFM の仕様では、インラインコードの中であっても区切りとして扱われるので、\| とエスケープします。

| 書き方 | 意味 |
| --- | --- |
| `a | b` | a または b |

このように書くと、3 行目は「`a」「b`」の 2 つのセルに分かれ、余った「a または b」は表示されません(GFM では、見出しの行より多いセルは捨てられます)。正しくは次のように書きます。表示では「\」が消え、インラインコードの中に a | b と表示されます。

| 書き方 | 意味 |
| --- | --- |
| `a \| b` | a または b |

表が表にならない

表が | の付いた文字のまま表示されるときは、次の 2 つを確認します。

  • 見出しの行と、その下の --- の行の列の数が同じか:GFM の仕様では、この 2 行のセルの数が違うと表として認識されません。| a | b | の下に | --- | と 1 列分だけ書くと、全体がただの段落になります。3 行目以降は列の数が違ってもよく、足りないセルは空になります。
  • 表の前に空の行があるか:GitHub Docs では、表を正しく表示するには表の前に空の行が必要とされています。説明の文のすぐ下に表を書かず、1 行空けます。

文章が急に大きな見出しになる

区切り線のつもりで、文章のすぐ下の行に --- を書くと、その文章が見出し(h2)になります。Markdown には、文字の下に === や --- を引いて見出しにする書き方(Setext 見出し)があるためです。区切り線を入れたいときは、--- の前に空の行を入れます。

説明の文章
---

上の 2 行は「説明の文章」という h2 の見出しになります。同じように、# の後にスペースがない #見出し は見出しにならず、そのまま文字として表示されます。

書いた README を確認して GitHub に上げる

  1. README.md の中身をすべて選択してコピーし、Markdownプレビューの「Markdown」の欄に貼ります。見出し・表・コードブロックの数が、プレビューの下に表示されます。
  2. VS Code を使っている場合は、README.md を開いて Ctrl + Shift + V を押すとプレビューが開きます。Ctrl + K を押してから V を押すと、編集画面の横に並べて表示します(VS Code のプレビューは CommonMark に沿っていると公式ドキュメントに書かれています)。
  3. 表示に問題がなければ、ターミナルで README.md をステージします。
git add README.md
  1. コミットします。
git commit -m "README を追加"

練習用のリポジトリで実行すると、次のように表示されました(63 行の README.md を追加した例です)。

[master (root-commit) b8f55db] README を追加
 1 file changed, 63 insertions(+)
 create mode 100644 README.md
  1. git push で GitHub に送り、ブラウザーでリポジトリのページを開いて、画像・相対リンク・タスクリストの表示を確かめます。

コミットの英数字(b8f55db)は、実行するたびに変わります。Git の初期設定やリモートリポジトリへの push がまだの人は、「Git入門:インストール後の初期設定から最初のコミットまで」を参考にしてください。

よくある質問

README は日本語と英語のどちらで書けばよいですか?

読む人に合わせて決めます。社内や日本語の利用者向けなら日本語で問題ありません。世界中の人に使ってほしいなら英語で書き、日本語版を README.ja.md のような別のファイルに分けて、相対リンクで行き来できるようにする方法がよく使われます。

Issue やプルリクエストのコメントも同じ書き方ですか?

同じ GFM の書き方が使えます。違いは改行で、Issue・プルリクエスト・ディスカッションでは Enter 1 回の改行がそのまま反映されます。README.md で同じ見た目にしたいときは、段落を分けるか、行末に「\」を付けます。

README が長くなってしまいました

README には、最初に読んでほしい内容(説明・インストール・基本の使い方)だけを残し、くわしい設定や開発者向けの説明は docs フォルダーの .md ファイルに分けて、相対リンクで案内します。GitHub は 500 KiB を超えた README を途中で切ってしまうので、大きな表やログを貼るのも避けます。

「*」や「#」を記号の意味なしで表示したいです

記号の前に「\」を付けると、記号として扱われずにそのまま表示されます。たとえば \*注意\* は、斜体にならずに「*注意*」と表示されます。コマンドやファイル名なら、インラインコード(`*.log` のようにバッククォートで囲む)にするほうが読みやすくなります。

まとめ

  • README は「名前と説明 → 主な機能 → 必要なもの → インストール → 使い方 → ライセンス」の順に書くと読みやすい
  • .md ファイルでは Enter 1 回の改行はつながる。段落を分けるか、行末に「\」
  • リストの入れ子は、親の文字の位置までスペースを入れる(- は 2 つ、1. は 3 つ)
  • コードブロックの中に ``` を書くときは外側を 4 つに。表の中の | は \|
  • リポジトリ内のファイルや画像へは、相対リンク・相対パスで書く

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました