テキスト・データ

マークダウン(Markdown)の書き方|見出し・リスト・表と改行の注意点

ほかの言語で読む: 한국어

マークダウン(Markdown)の書き方の基本は、行の先頭や文字の前後に半角の記号を置くことです。見出しは行頭に #、箇条書きは -、リンクは 表示する文字 と書き、行頭の記号の後には半角スペースを1つ入れます。また、Enterを1回押しただけでは改行されないことが多いので、空行を入れるか、行末に半角スペースを2つ置きます。

Markdownは、プレーンテキスト(文字色などの装飾情報を持たない、ただの文字)で書いた文章をHTMLなどの見やすい形式に変換するための記法です。GitHubのREADME、技術ブログ、ノートアプリ、チャットツールなどで広く使われています。

この記事では、主な記法を「Markdownの書き方」と「変換後のHTML」を並べて説明します。あわせて、全角記号やスペースの入れ忘れ、改行など、日本語入力で起きやすい失敗とその直し方もまとめます。

マークダウンの書き方早見表|記号と変換後のHTML

Markdownには表記の違う「方言」がいくつかあります。代表的なのは次の2つです。

  • CommonMark:もともとあいまいだったMarkdownの解釈を細かく決めた標準仕様
  • GitHub Flavored Markdown(GFM):CommonMarkをもとに、GitHubが表・チェックボックス・取り消し線などを追加した拡張仕様

下の表は、主な記法と変換後のHTMLを並べたものです(「GFM」と書いたものは拡張記法です。HTMLは読みやすいように改行を省いています)。

書きたいもの Markdown 変換後のHTML
大見出し # 見出し <h1>見出し</h1>
中見出し ## 見出し <h2>見出し</h2>
太字 **重要** <strong>重要</strong>
斜体 *強調* <em>強調</em>
箇条書き - 項目 <ul><li>項目</li></ul>
番号付きリスト 1. 手順 <ol><li>手順</li></ol>
リンク 公式 <a href="https://example.com">公式</a>
画像 ! の直後に 説明(間を空けない) img 要素(src属性が photo.png、alt属性が「説明」)
引用 > 引用文 <blockquote><p>引用文</p></blockquote>
インラインコード `npm install` <code>npm install</code>
区切り線 --- <hr />
取り消し線(GFM) ~~旧価格~~ <del>旧価格</del>

記号はすべて半角です。この「半角であること」と「記号の後のスペース」が、日本語で書くときの最大のつまずきポイントになります。

見出し・強調・引用の書き方

見出しは「#」の数でレベルが決まる

行頭に # を1〜6個置き、半角スペースを空けて見出しの文字を書きます。# 1個が <h1>、6個が <h6> です。文書のタイトルにあたる大見出しは # プロジェクト名 のように # を1個にし、その下の章や項目は次のように # を増やしていきます。

## インストール
### 動作環境

CommonMarkでは #見出し のようにスペースがないと見出しになりません。古い変換器では通ることもあるため、「ある環境では見出しになったのに別の環境ではならない」という差が生まれます。

もう一つの落とし穴が、文章の直下に書いた --- です。

今日の作業メモ
---

これは区切り線ではなく、上の行が <h2>今日の作業メモ</h2> という見出しになります(下線を引くように見出しを作る「Setext見出し」という書き方)。区切り線にしたいときは --- の前に空行を入れるか、*** を使います。

太字・斜体は「」に隣接すると効かないことがある

**太字** と *斜体* が基本です。ただし、日本語では次のような書き方が太字になりません。

この手順は**「必須」**です。

CommonMarkには、記号の前後の文字が句読点・括弧かどうかで強調の開始・終了を判定するルールがあります。** の内側が括弧で、外側が「は」「で」のような普通の文字だと条件を満たさず、** がそのまま表示されます。

括弧を外側に出して この手順は「**必須**」です。 と書けば、多くの環境で正しく太字になります。

引用は行頭に「>」

> 引用したい文章です。
>> 引用の中の引用です。

> を重ねると入れ子の引用になります。複数行を1つの引用にまとめたいときは、各行の先頭に > を付けます。

箇条書きと番号付きリストの書き方

箇条書きは「-」「*」「+」のどれか

行頭に - と半角スペースを置きます。* や + でも同じ結果になりますが、1つのリストの中で記号を混ぜると、別のリストとして分かれる場合があります。どれか1つに統一するのが安全です。

番号付きリストは数字が自動で振られる

1. 材料をそろえる
1. 下ごしらえをする
1. 焼く

CommonMarkでは、最初の番号だけが使われ、2行目以降の数字は無視されます。そのため上の例は「1、2、3」と表示されます。途中に手順を追加しても番号を書き直さずに済むので、すべて 1. で書く人もいます。

最初を 3. にすると <ol start="3"> となり、3から始まるリストになります。ピリオドの代わりに 1) も使えます。

入れ子は半角スペースで字下げする

- 果物
  - りんご
  - みかん
- 野菜

子の項目は、親の文字の開始位置に合わせて字下げします。- の下なら半角スペース2個、1. の下なら3個が基準です。4個にしておけばどちらでも通りやすくなります。全角スペースで字下げすると、入れ子として認識されません。

チェックボックスはGFMの拡張記法

- [ ] 見積書を送る
- [x] 請求書を送る

[ ] が未完了、[x] が完了です。GFMに対応した環境ではチェックボックス付きのリストになりますが、CommonMarkだけの環境では [ ] がそのまま文字として表示されます。

リンク・画像・コードブロックの書き方

リンクとURLの注意点

表示する文字 が基本です。公式サイト のように、URLの後に半角スペースと "説明" を書くと、マウスを乗せたときに表示される説明文(title属性)になります。

URLだけを書いて自動でリンクにしたい場合、CommonMarkでは <https://example.com> のように < > で囲みます。GFMでは囲まなくても自動リンクになります。

URLに半角スペースが含まれると、リンクとして認識されず記号がそのまま表示されます。スペースは %20 に置き換えるか、文字 のように < > で囲みます。日本語を含むURLのパーセントエンコード(文字を「%」と英数字の組み合わせに置き換える方式)はURLエンコード・デコードでもできます。

画像はリンクの先頭に「!」

画像は、リンクと同じ 代替テキスト の形の直前に、半角の ! を付けて書きます。! と `` の間にスペースを入れると、画像ではなく「!」という文字とリンクに分かれてしまいます。

たとえば代替テキストが「操作画面のスクリーンショット」、ファイルが images/screen.png なら、! に続けて [操作画面のスクリーンショット と書きます。

[ ] の中は画像の代替テキスト(alt属性)になり、画像が表示できないときや読み上げソフトで使われます。「画像」とだけ書かず、内容がわかる説明を入れます。

コードブロックとREADMEの例

文中の短いコードはバッククォート(`)で囲みます。JIS配列のキーボードでは、多くの場合 Shift+@ で入力できます。

複数行のコードは、バッククォート3つの行で上下を挟みます。開始行に言語名を書くと、対応する環境では色分け表示されます。

READMEでは、1行目にプロジェクト名を # file-renamer のように大見出しで書き、その下に次のような概要と章を続ける構成がよく使われます。

ファイル名を一括で変更するコマンドラインツールです。

## インストール

```bash
npm install -g file-renamer
```

## 使い方

1. 対象のフォルダに移動します
2. `file-renamer --lower` を実行します

詳しくはドキュメントを参照してください。

言語名付きのコードブロックは、CommonMarkでは <pre><code class="language-bash"> のように変換されます。実際の色分けは表示する側の仕組みが担当するため、同じ書き方でも色が付く環境と付かない環境があります。

表の書き方とGitHub Flavored Markdownの拡張記法

表の基本と左右・中央寄せ

表は標準のCommonMarkにはなく、GFMなどの拡張記法です。

| 商品 | 数量 | 価格 |
| :--- | :---: | ---: |
| りんご | 3 | 300円 |
| みかん | 10 | 450円 |

1行目が見出し行、2行目が区切り行です。区切り行のコロンの位置で揃え方が決まり、:--- が左寄せ、:---: が中央寄せ、---: が右寄せです。金額や数量の列は右寄せにすると桁がそろって読みやすくなります。

表を書くときは、次の点を守ると崩れにくくなります。

  • 見出し行と区切り行のセルの数を同じにする(GFMでは一致しないと表として認識されない)
  • 区切り行のハイフンは3個以上にしておく(少なくても通る環境はあるが、3個なら安全)
  • 表の直前に空行を入れる
  • セルの中で縦線を文字として使うときは \| と書く

列の幅を記号でそろえる必要はありません。セル内の改行はGFMの表記法にはないため、HTMLタグが使える環境では <br> で代用します。

環境ごとの対応の違い

記法 CommonMark GFM
見出し・リスト・リンク・引用 対応 対応
表 非対応 対応
チェックボックス 非対応 対応
取り消し線 非対応 対応
URLだけの自動リンク < > で囲めば対応 囲まなくても対応

ブログサービス、ノートアプリ、チャットツールは、それぞれ独自の方言を採用しています。改行の扱いや対応する記法が異なるため、公開先のヘルプで確認してから書くのが確実です。

Enter1回で改行されないのはなぜ?改行の正しい書き方

1回の改行は「スペース」として扱われる

東京都千代田区
1丁目2番3号

これは1つの段落(<p>)として変換され、表示は「東京都千代田区 1丁目2番3号」のように1行になります。Markdownは、文章の途中の改行を「書きやすさのための折り返し」とみなすためです。

HTMLの中には改行が残りますが、ブラウザは改行をスペースとして表示します。そのため日本語の文章では、つなげたつもりの文字の間に小さな隙間が入ることがあります(ブラウザによって異なります)。

改行する方法は4つ

方法 書き方 変換結果 注意点
空行を入れる 行と行の間に空の行を1つ 別々の段落 段落の間に余白が入る
行末に半角スペース2つ 「千代田区」の後にスペース2つ <br /> 見えないため消えやすい
行末にバックスラッシュ 千代田区\ <br /> CommonMark準拠の環境で有効
HTMLタグ 千代田区<br> <br> HTMLが使える環境のみ

行末スペースの方法は、エディタの「保存時に行末の空白を削除する」設定が有効だと、保存のたびに消えてしまいます。見た目で確認できるバックスラッシュのほうが管理しやすい場面もあります。

表示先によって改行の扱いが変わる

GitHubでは、リポジトリ内の .md ファイルでは1回の改行が反映されません。一方、IssueやPull Requestのコメントでは、Enter1回の改行がそのまま反映されます。チャットツールにも、Enter1回で改行されるものが多くあります。

同じ文章でも表示先で見え方が変わるため、「別の場所に貼ったら改行が消えた」というときは、まず表示先の仕様を疑います。

全角記号やスペース忘れなど日本語入力でのつまずき

日本語入力(IME)がオンのまま記号を打つと、全角の記号が入ってしまいがちです。Markdownは半角記号しか認識しないため、見た目は似ていても記法として働きません。全角と半角の違いは文字数の数え方|スペース・改行・全角半角・絵文字の扱いを解説でも詳しく説明しています。

症状 よくある原因 直し方
「#見出し」とそのまま表示される #が全角 半角の # に直す
#見出し が見出しにならない # の後にスペースがない # 見出し とする
半角の # なのに効かない 後ろのスペースが全角 半角スペースに直す
太字にならず記号が残る *が全角、または「」に隣接 半角の * にし、括弧を外に出す
番号付きリストにならない 「1.」のように数字やピリオドが全角 1. と半角で書く
リンクにならない []()が全角 半角の [ ]( ) に直す
表が崩れる 縦線が全角、またはセル数が不一致 半角の縦線にし、セル数をそろえる
入れ子のリストが平らになる 全角スペースで字下げ 半角スペース2〜4個にする
行末の \ やエスケープが効かない ¥(円記号)が入力されている バックスラッシュを入力する
普通の文章が見出しになる 文章の直下に --- 前に空行を入れる

円記号について補足します。Windowsの日本語フォントでは、バックスラッシュが¥の形で表示されることがありますが、中身がバックスラッシュなら問題なく動きます。macOSのJIS配列では、設定によって¥キーで円記号そのものが入力されます。その場合は、Optionキーを押しながら¥キーを押すか、入力ソースの設定で切り替えます。

予防策としては、記号を打つときだけ半角英数モードに切り替えるのが確実です。IMEによっては、記号を常に半角で入力する設定もあります。書き終えたら、エディタの検索で「#」「*」「全角スペース」を探すと、見落としをまとめて見つけられます。

書いたMarkdownをHTMLに変換して確認する手順

公開前にプレビューで確認すると、全角記号やスペース忘れにすぐ気づけます。

  1. 書いた文章をMarkdown HTML変換に貼り付けます。
  2. プレビューで、見出し・リスト・リンクが意図どおりの形になっているかを見ます。
  3. # や ** が文字のまま残っている行があれば、その行の記号が半角か、記号の後に半角スペースがあるかを確認します。
  4. 出力されたHTMLで <p> と <br /> の位置を見て、改行が段落区切りになっているのか、行内の改行になっているのかを確かめます。
  5. 表やチェックボックスなどの拡張記法を使った場合は、公開先の環境が対応しているかを最後に確認します。

HTMLの出力を見る習慣をつけると、「なぜここで段落が分かれたのか」「なぜ改行が消えたのか」を自分で判断できるようになります。

Markdownを書くときのチェックリスト

  • 記号(# * - > [ ] ( ) と縦線)はすべて半角か
  • 行頭の記号の後に半角スペースを1つ入れたか
  • リンクは 表示する文字 の形で、URLに半角スペースが入っていないか
  • 見出し・リスト・表・コードブロックの前後に空行を入れたか
  • 行内の改行には、行末スペース2つかバックスラッシュを使ったか
  • 区切り線の --- の前に空行があるか
  • 太字の ** を「」の内側ではなく外側に置いたか
  • 入れ子のリストは半角スペースで字下げしたか
  • 表の見出し行と区切り行のセル数がそろっているか
  • 表・チェックボックス・取り消し線を使う場合、公開先がGFMなどの拡張記法に対応しているか
  • 画像の [ ] に内容がわかる代替テキストを書いたか

よくある質問

Markdownのファイルは何で作り、拡張子は何にすればよいですか?

Markdownはただのテキストなので、メモ帳などのテキストエディタで作れます。拡張子は「.md」が一般的で、「.markdown」も使われます。文字コードはUTF-8で保存しておくと、多くの環境で文字化けせずに扱えます。

「#」や「*」を記法ではなく文字として表示したいときはどうしますか?

記号の直前にバックスラッシュを付けると、記法として解釈されずにそのまま表示されます(例:# や *)。行頭の「2024.」のような数字とピリオドがリストになってしまう場合は、「2024.」のようにピリオドの前にバックスラッシュを入れます。インラインコードで囲む方法もあります。

空行を何行も入れているのに、段落の間隔が広がらないのはなぜですか?

Markdownでは、連続した空行はいくつあっても空行1つと同じ「段落の区切り」として扱われるためです。間隔をさらに広げる記法は標準にはありません。HTMLが使える環境なら <br> タグなどで調整できますが、表示先によっては取り除かれることがあります。

Markdownで文字の色や大きさを変えることはできますか?

標準のMarkdownには、文字色や文字サイズを指定する記法はありません。HTMLタグが使える環境ではタグで指定する方法もありますが、多くのサービスは安全のため一部のタグや属性を取り除くので、反映されないことがあります。見出しや太字など、Markdownの記法で表現できる範囲で強弱をつけるのが確実です。

表示されないメモ(コメント)をMarkdownの中に書けますか?

HTMLのコメント記法(<!-- メモ -->)を使うと、多くの環境で表示されないメモとして扱われます。ただし、変換後のHTMLのソースには残る場合があるため、公開してはいけない情報は書かないようにします。表示先によって扱いが異なるので、念のためプレビューで確認してください。