「公式ドキュメント通りに **太字** って書いたのに、なぜか記号がそのまま表示される」「別のツールでは効いたのに、こっちでは反映されない」。Markdownを使っていると、一度はこの謎現象にぶつかったことがあるのではないでしょうか。
実はこれ、書き方が間違っているとは限りません。Markdownには複数の「方言」が存在し、さらにツールごとにどこまで解釈するかの実装差があるため、同じ記述でも結果が変わることがあるのです。
この記事では、まずMarkdownの基本記法を一覧で整理したうえで、「反映されない」が起きる技術的な理由を掘り下げます。読み終える頃には、うまくいかない原因を自分で切り分けられるようになるはずです。
この記事のポイント
- 見出し・強調・リスト・表など、基本的なMarkdown記法を一覧で確認できる
- Markdownには「CommonMark」「GFM」など複数の仕様（方言）が存在する
- 同じ記法でも反映される/されないが分かれる技術的な理由を理解できる
まずはMarkdown基本記法の一覧
細かい話に入る前に、よく使われる基本記法を整理しておきます。多くの環境で共通して使える、比較的「揺れが少ない」記法です。
| 記法 | 書き方 | 用途 |
|---|---|---|
| 見出し | # 〜 ###### |
h1〜h6に対応 |
| 強調（太字） | **太字** |
strong要素 |
| 強調（斜体） | *斜体* または _斜体_ |
em要素 |
| 箇条書き | - または * + 半角スペース |
ul要素 |
| 番号付きリスト | 1. + 半角スペース |
ol要素 |
| リンク | [表示文字](URL) |
a要素 |
| 画像 |  |
img要素 |
| 引用 | > 引用文 |
blockquote要素 |
| インラインコード | `コード`（バッククォート1つで囲む） | code要素 |
| コードブロック | バッククォート3つで前後を囲む | pre + code要素 |
| 水平線 | ---（前後に空行が必要） |
hr要素 |
| 表 | | と - で罫線を表現 |
table要素（GFM拡張） |
| タスクリスト | - [ ] / - [x] |
チェックボックス付きli（GFM拡張） |
この一覧を見て「表とタスクリストだけ書き方がちょっと特殊だな」と感じた方は、勘がいいです。実はここが、後述する「反映されない問題」の入口にもなっています。
なぜ「書いたはずなのに反映されない」が起きるのか
結論から言うと、原因は主に次の5つに分類できます。1つずつ見ていきましょう。
原因1：Markdownには「方言」が存在する
Markdownはもともと一人の開発者が考案した軽量な記法でしたが、その後さまざまな実装が生まれ、解釈にばらつきが出てしまいました。この問題を解消するために標準化を目指したのがCommonMarkという仕様です。
一方、GitHubが採用しているGFM（GitHub Flavored Markdown）は、CommonMarkをベースにしつつ、表・タスクリスト・自動リンクなど独自の拡張を追加しています。つまり「GFMでは表が書けるのに、別の環境では罫線がそのまま文字として表示される」というのは、方言の違いによる正常な挙動なのです。
原因2：拡張機能がそもそも無効になっている
表やタスクリストのような拡張記法は、パーサー側で明示的に機能を有効化しないと動かない実装も存在します。エディタやCMSの設定画面で、拡張機能のオン・オフを切り替えられるケースもあるため、記法自体は合っていても設定が原因で反映されないことがあります。
原因3：改行・空行のルールが厳密
Markdownは見た目以上に空白や改行のルールにシビアです。例えば見出しの前後に空行がないと段落として扱われたり、リストの直前に空行がないと箇条書きとして認識されなかったりします。また、文末にスペースを2つ入れるかどうかで「改行」の扱いが変わる実装もあります。
原因4：HTMLとの混在で意図せず打ち消される
Markdown内にHTMLタグを直接書ける仕様上、意図せずHTMLタグと解釈されてしまい、その内側のMarkdown記法が無効になることがあります。特に <div> などのブロック要素で囲った内側は、Markdownとして処理されない実装が多い点に注意が必要です。
原因5：そもそもMarkdownを解釈しない環境で使っている
見落としがちですが、投稿先のプラットフォームがMarkdownをネイティブに解釈しない場合もあります。例えばBloggerは基本的にHTMLで記事を管理する仕組みのため、Markdownの記号をそのまま入力しても、多くの場合はただの文字列として表示されます。この記事のHTMLコードも、Markdownではなく直接HTMLタグで組んでいるのはこのためです。
| 方言・環境 | 表・タスクリストの扱い |
|---|---|
| CommonMark（標準仕様） | 表・タスクリストは仕様に含まれない |
| GFM（GitHub等） | 表・タスクリストともに拡張として利用可能 |
| Blogger | Markdown自体を基本的に解釈しないため、HTMLで記述する必要がある |
手元の環境がどれに該当するかは、公開日時点の各サービスの公式ドキュメントで確認するのが確実です。仕様は変更されることもあるため、迷ったら最新情報をチェックする習慣をつけておくと安心です。
反映されないときのチェックリスト
実際にうまく表示されないときは、次の順番で確認してみてください。
- 見出しやリストの前後に空行を入れているか
- リストの記号（
-や1.）の後に半角スペースを入れているか - 使っている環境がGFM系か、CommonMark系か把握しているか
- 表やタスクリストなどの拡張機能が設定で無効化されていないか
- HTMLタグで意図せず囲ってしまっていないか
- そもそもその投稿先がMarkdownを解釈する仕組みかどうか
まとめ
Markdownが反映されない現象は、書き方のミスだけでなく、方言の違い・拡張機能の設定・改行ルール・HTMLとの混在・そもそも解釈されない環境という、複数の技術的な要因が重なって起きています。
次にうまく反映されないと感じたら、まず「自分が今どの方言の、どの設定の環境で書いているか」を確認してみてください。原因の切り分けがぐっと楽になるはずです。
0 件のコメント:
コメントを投稿