Markdownのチェックボックスが表示されない原因｜スペース・ネスト・GFM対応の落とし穴
Markdownのチェックボックス（タスクリスト）が四角い見た目にならず、[ ]という文字列のまま表示される場合、原因は「[ ]」内外のスペース不足か、リストのネストのインデントずれ、あるいはそもそも使っているツールがGFMのタスクリスト拡張に対応していないかのいずれかにほぼ絞られます。順に切り分け方を解説します。
チェックボックス記法の基本構文
Markdown本体（CommonMark）の仕様にはチェックボックスという概念はありません。GitHubが提案し、GitHub・Qiita・Zennなど多くのサービスが採用しているGFM（GitHub Flavored Markdown）のタスクリスト拡張という追加仕様です。
- [ ] 未完了のタスク
- [x] 完了したタスク見た目は単なる箇条書きに似ていますが、パーサー側は「箇条書きのマーカーの直後に[ ]または[x]が続き、その後にスペースが1つある」という形をタスクリストとして特別に検出しています。この検出条件の細かさが、崩れの原因のほとんどを占めています。
原因1：「[ ]」の中と後のスペースが不足している
もっとも多い原因です。次の3か所のスペースがすべて必要です。
| 位置 | 正しい例 | よくある間違い |
|---|---|---|
マーカーと[の間 | - [ ] | -[ ]（詰めて書いている） |
[と]の間 | [ ]（半角スペース1個） | []（スペースなし） |
]と本文の間 | [ ] タスク | [ ]タスク（詰めて書いている） |
特に「[と]の間のスペースなし」は見た目でほぼ気づけません。未完了は[ ]（半角スペース1個を挟む）、完了は[x]（小文字または大文字のx）と決まっており、空文字の[]はタスクリストとして認識されず、ただの文字列として表示されます。
原因2：箇条書きのマーカーとして認識されていない
タスクリストはあくまで箇条書き（- * +）または番号付きリストの拡張です。行頭に箇条書きのマーカーがない状態で[ ]だけを書いても、タスクリストにはなりません。
[ ] タスクこの書き方は、多くのGFM実装でただの段落テキストとして扱われます。必ず-などのリストマーカーを先頭に置いてください。
- [ ] タスク原因3：ネストしたチェックボックスのインデント幅がずれている
親タスクの下に子タスクをぶら下げる場合、インデントの幅が親リストと合っていないと、子リストとして認識されず表示が崩れます。
- [ ] 親タスク
- [ ] 子タスク1
- [ ] 子タスク2インデントは半角スペース2〜4個、または半角スペース1個+タブなど、パーサーによって許容幅の解釈が微妙に異なります。全角スペースでインデントを入れてしまうと、ほぼ確実にネストとして認識されません。エディタの自動インデント機能がタブと半角スペースを混在させることがあるため、崩れた場合はインデント文字を統一して打ち直すのが確実です。
原因4：直前に別のブラケット表記があり競合している
[ ]や[x]の前に、リンクの参照定義や独自の記法（[TODO]のようなラベル表記など）を置くと、パーサーがタスクリストのマーカーとして認識できず、通常の文字列やリンク構文として解釈されてしまうことがあります。
- [TODO][ ] 資料を作成するこの例では[TODO]がリンク参照ラベルのように解釈され、後続の[ ]がタスクリストのマーカーとして機能しない場合があります。他の記法をチェックボックスの直前に置かない、という単純なルールで避けられます。
原因5：全角文字や記号違いの「x」を使っている
チェック済みを表す[x]のxは、半角の英字（小文字xまたは大文字X）である必要があります。日本語入力中に変換で紛れ込む全角の「ｘ」や、レ点・チェックマークの絵文字（✓・✔️）を[ ]の中に入れても、GFMのタスクリスト拡張としては認識されません。
- [ｘ] 完了のつもり（全角のため無効）
- [✓] 完了のつもり（絵文字のため無効）
- [x] 正しい書き方見た目は「チェックを入れたつもり」でも、パーサーからは中身が空でない[ ]と区別がつかないため、未完了のチェックボックスとして表示されるか、実装によってはタスクリストとして認識されず崩れます。
原因6：コードブロックの中に書いてしまっている
``` `で囲ったコードブロックの中に- [ ] タスクと書いても、それは**コードとしてそのまま表示するための領域**なので、タスクリストとしては解釈されません。技術記事の中で「Markdownの書き方」を説明する目的でコードブロックに囲んで見せているだけなのに、実際にタスクリストとして機能させたい行まで誤ってコードブロックの中に入れてしまっているケースが時々あります。囲んでいる``の位置がずれていないか、意図した行がコードブロックの外に出ているかを確認してください。
見落としがちな原因：ツールがGFMのタスクリスト拡張に対応していない
構文がすべて正しいのに[ ]が文字のまま表示される場合、使っているツールがGFMのタスクリスト拡張そのものを実装していない可能性があります。これはMarkdownの表が崩れる原因と同じ構造の問題で、表もチェックボックスも「Markdown本体の仕様ではなく、GitHubが拡張した仕様」だからです。
実際に、当サイトのMarkdownプレビューツールで- [ ] タスクと入力すると、見出し・箇条書き・強調・リンク・コードブロックといった基本構文はプレビューされますが、タスクリスト記法は未実装のため[ ] タスクという文字列のまま箇条書きの中に表示されます。「Markdown対応」を謳うツールであっても、対応範囲は実装ごとに差があるということの分かりやすい実例です。崩れの原因を切り分ける際は、GitHubやQiitaなどGFMのタスクリスト拡張に対応していることが明確なサービスで同じテキストを試し、そちらで正しく表示されるなら、元のツール側の未対応が原因だと判断できます。
他所ではあまり書かれていない落とし穴：チェックを入れても保存されない
構文が正しく表示できても、次でつまずく人が少なくありません。プレビュー画面や公開済みページで四角いチェックボックスをクリックしても、多くの場合は元のMarkdownファイルの中身は書き換わりません。
GitHubのIssueやPull Requestのように、クリックした操作が裏側で元のファイル（またはコメント本文）を自動的に書き換えてくれる特殊な実装を持つサービスは一部にとどまります。それ以外の大半のMarkdownビューアやブログ、静的サイトでは、チェックボックスはdisabled属性付きのHTML要素として描画されているだけで、表示上クリックできても状態は保存されず、ページを再読み込みすれば[ ]の状態に戻ります。
「チームでタスクの進捗をチェックボックスで共有したいのに、誰かがチェックを入れても反映されない」という相談の多くは、構文の誤りではなく、この保存の仕組みがそもそも存在しないという前提の見落としが原因です。進捗管理そのものが目的なら、Markdownのチェックボックスは見た目の表現にとどめ、実際の管理はIssueやタスク管理ツール側で行うと割り切ったほうが混乱を避けられます。
まとめ
[ ]は中にスペース1個、前後にも半角スペースが必要（-[ ]や[]は認識されない）- チェックボックスは箇条書き・番号付きリストの拡張機能であり、単独の
[ ]では機能しない - ネストする場合はインデント幅を統一する（全角スペースの混入に注意）
[ ]の直前に他のブラケット記法を置かないxは半角の英字のみ有効。全角文字やチェックマーク絵文字は無効- 意図した行がコードブロックの中に入り込んでいないか確認する
- 構文が正しくても表示されない場合は、ツールがGFMのタスクリスト拡張に対応しているかを疑う
- チェックのクリックは多くの環境で保存されない。進捗管理が目的ならタスク管理ツールを使う
原因を上から順に確認すれば、ほとんどのケースは特定できます。