Markdownのコードブロック完全ガイド｜書き方・言語指定・崩れる原因と直し方

Markdownでコードブロックを書いたはずなのに、表示が崩れて読めなくなる。リストの途中に入れた瞬間、次の見出しまでコード扱いになってしまう。環境が変わると色が付かず、説明文の意味が通らなくなる――こうしたトラブルに心当たりがある方は少なくありません。

コードブロックの問題は、知識不足ではなく書き方が体系化されていないことが原因で起こります。本記事では、Markdownのコードブロックを「誰が書いても、どの環境でも、崩れにくい形」で提示するために、基本のテンプレから、入れ子で失敗しやすいポイント、レビューで使えるチェックリストまでを一つずつ整理いたします。ドキュメントの信頼性と読みやすさを同時に高めたい方に向けた、再現性重視のガイドです。

※本コンテンツは「記事制作ポリシー」に基づき、正確かつ信頼性の高い情報提供を心がけております。万が一、内容に誤りや誤解を招く表現がございましたら、お手数ですが「お問い合わせ」よりご一報ください。速やかに確認・修正いたします。

Markdownのコードブロックとは何か

インラインコードとコードブロックの違い

Markdownでコードを表現する方法は大きく分けて2種類あります。違いを誤解すると「ブロックにすべき内容をインラインで書いて読みにくい」「インラインにすべき短い語句をブロックにして冗長」といった品質低下が起きます。

• インラインコード：文章の流れの中で、コマンド名・関数名・設定キーなどの短い要素を示す用途
  例：npm install、SELECT、user_id

• コードブロック：複数行のコード、ログ、設定ファイル、入出力例などを、まとまりとして提示する用途
  例：シェル手順、YAML設定、JSONレスポンス、スタックトレース

使い分けの判断基準として、次のルールが分かりやすいです。

• 1行で完結し、文章の途中に埋め込めるならインライン

• 改行がある、またはコピペ実行を想定するならコードブロック

加えて、コードブロックには「見た目の整形」だけでなく、次の実務的な価値があります。

• 記号（*、_、#、>など）を含む内容でも、Markdown装飾として誤解釈されにくい

• 等幅フォントで表示され、インデント（字下げ）構造を表現しやすい

• 「コピペの範囲」が明確になり、読者が余計な文章を巻き込んでコピーしにくい

つまり、コードブロックは「見栄え」だけでなく、誤操作や読み違いを減らすための記法として位置づけるのが適切です。

コードブロックでMarkdown装飾が効かない理由

コードブロック内では、通常のMarkdown装飾（太字、リンク、見出し、箇条書き等）が基本的に効きません。これは「不便」ではなく、コードを文字どおりに扱うための設計思想です。

例えば、次のような文字列は通常の本文では箇条書きに解釈されます。

• - item

• * item

しかし、コード例として示したいときに箇条書きとして解釈されると、記号が消えたり、構造が変わったりして意図が崩れます。コードブロック内で装飾が無効になることで、次のメリットが得られます。

• #include <stdio.h> の # が見出し扱いにならない

• * や _ を含む正規表現が強調扱いにならない

• YAMLやPythonのインデントがそのまま保持され、意味を失いにくい

強調したい場合は、コードブロック内で無理に装飾しようとせず、コードブロックの外側で説明文として補足するのが最も安全です。

Markdownのコードブロックの基本の書き方

コードブロックの書き方は主に2つあります。現場では「フェンス形式」が主流ですが、「インデント形式」も知っておくと、古い文書や特殊な環境での対応力が上がります。

フェンス形式の最小テンプレ

フェンス形式は、バッククォート3つ（“`）または チルダ3つ（~~~）で、コードの開始と終了を囲む方法です。

1. 開始フェンスと終了フェンスを必ずセットで書くこと

2. 開始と終了は同じ文字種（バッククォート同士、チルダ同士）に揃えること

フェンス形式は、表示実装ごとの差が比較的小さく、複数行の提示にも向きます。さらに、後述する「言語指定」を付けやすい点でも利便性が高いです。

実務上の推奨は以下です。

• チームでバッククォートに統一（入力しづらい環境ならチルダに統一）

• フェンスの前後に空行を置く（入れ子構造の誤解釈を防ぐ）

• 終了フェンスは「後で足す」のではなく、最初に両方打ってから中身を書く（閉じ忘れ防止）

たとえば、作業手順としては次の順序が堅実です。

1. const x = 1;
   console.log(x);

2. 改行して内容を書く

3. 最後に “` を入力して終了フェンス

4. その後で内容を整える

この癖づけだけで、閉じ忘れ事故が大きく減ります。

インデント形式の使いどころ

インデント形式は、各行の先頭を4スペース（またはタブ1つ）でインデントする方法です。例は次のとおりです（可視化のため、ここでは見た目上スペースを含めています）。

インデント形式の長所と短所を整理いたします。

長所

• フェンスの「閉じ忘れ」が原理的に起きにくい（インデントが切れれば終わるため）

• 古いMarkdown実装でも動作しやすい場合がある

短所

• 箇条書きや引用の中に入ると、インデントが混ざりやすく、見た目も崩れやすい

• エディタやツールの自動整形でスペース数が変わり、意図しない範囲がコード化することがある

• 言語指定（ハイライト指定）を付けにくい

そのため、現代のチーム運用では次の使い分けが現実的です。

• 新規作成ドキュメント：フェンス形式を原則

• 過去資産の互換維持、またはフェンスが不安定な環境：必要に応じてインデント形式

「どちらが正しいか」ではなく、チームの表示環境で安定する方を標準にして統一するのが最重要です。

言語指定とシンタックスハイライトの考え方

フェンス形式では、開始フェンスの直後に文字列を付けることで、しばしば「言語指定（info string）」として扱われます。一般的な例は次のとおりです。

次の項目に進みます

注意点は以下です。

• 引用の各行に > を付ける必要があり、編集時のミスが起きやすい

• ツールによっては引用内フェンスを期待どおりに扱わない場合がある

• 長いコードを引用内に入れると、右に寄って読みづらくなる

そのため、運用としては次の方針が堅実です。

• 引用内には「解説文のみ」を置き、コードブロックは引用の外に出す

• 引用内に置くのは短い例、もしくは1〜3行程度に留める

• 長い例は、引用を使わずセクション分けで整理する

崩れ方別の原因と対処

Markdownのコードブロックを読みやすくする工夫

「崩れない」だけでは、良いドキュメントになりません。読み手が迷わず、正確に実行できる形に整える工夫が重要です。

短い例と長い例の出し分け

例の出し方は、情報密度と理解のしやすさに直結します。出し分けの基準例は次のとおりです。

• 短い例（1行）：インラインコードで提示し、前後の文章で意味を補う
  例：--help を確認してください。

• 中程度（3〜15行）：コードブロックで提示し、直後に要点を箇条書きで整理する

• 長い例（15行以上）：全文を載せず、重要部分の抜粋＋省略表現＋リンク（社内なら参照先）で提示する

長い例を全文掲載すると、読者は「どこが重要か」を見失いがちです。重要部分にコメントを付け、説明文側で「見るべき行」を明示すると理解が早くなります。

コピペ事故を減らす書き方

ドキュメントで最も避けたいのは、読者が誤って危険なコマンドを実行することです。コピペ事故を減らすための具体策は次のとおりです。

• プレースホルダを明確にする
  YOUR_API_KEY や YOUR_PROJECT_ID のように、置換が必要な値を一目で分かる表記にします。

• 危険な操作はワンクッション置く
  削除・上書き・本番反映などは、前置きで注意喚起し、可能なら安全オプションを付けます。
  例：rm -i、--dry-run、--check

• 入力プロンプト記号を混ぜない
  $ や > を入れると、読者がそのまま貼り付けて失敗することがあります。チームの方針として「プロンプトを入れる／入れない」を統一してください。一般には「入れない」方が事故が減ります。

例として、次のように「目的」と「注意」をコードブロックの外に置くと安全です。

目的：ログファイルのみを削除します（実行前に対象を確認してください）。

ここでは ls と rm を分けることで、読者に確認行動を促しやすくなります。

差分レビューで見落としを減らすルール

複数人で編集する環境では、レビューで見落としを減らすルールが重要です。以下は運用に乗せやすいルール案です。

• コードブロックはフェンス形式に統一し、バッククォートで統一する

• フェンス前後に空行を入れる（特にリスト内）

• 言語指定は、必須のものだけ付ける（JSON/YAML/diffなど）

• コードブロック内には「実行前提の一連」を入れ過ぎない（確認コマンドと破壊コマンドは分ける）

• 変更差分が大きい場合は、Markdownプレビューでコードブロック境界を必ず確認する

「ルールは少なく、守りやすく」が鉄則です。ルールが多いと形骸化しやすいため、まずは「フェンス統一」「空行」「リスト内テンプレ」から導入するのが適切です。

Markdownのコードブロックのトラブルシューティング

ここでは、現場で頻出するトラブルを「再現→原因→対処」で整理いたします。

バッククォートを本文に表示したい

コードブロックの説明をしていると、バッククォート（“`）自体を表示したい場面が出てまいります。その場合、次の方法が使えます。

方法1：外側をチルダフェンスにする
バッククォートを説明したいとき、外側を ~~~ にすると中に “` を置きやすくなります。

方法2：外側のバッククォートを増やす
外側を ““（4つ以上）にして、内側に “` を含めます。

この考え方は「外側の区切りを内側より強くする」というものです。説明文でフェンスを扱う際には非常に有効です。

実務上は、テンプレとして次のどちらかに寄せると混乱が減ります。

• 「Markdown記法を説明する章だけ、外側はチルダにする」

• 「Markdown記法を説明する章では、外側を4バッククォートにする」

言語指定しても色が付かない

言語指定しても色が付かない場合、原因は大きく次の3系統です。

1. 環境がハイライト未対応（機能が無い、または無効化されている）

2. 言語名が環境の期待と違う（例：shellは非対応だがbashは対応など）

3. 表示がプレーンテキスト扱い（セキュリティ設定や独自仕様）

このときの現実的な対処は以下です。

• 色が付かなくても読めるよう、インデント・改行・コメントで構造を明確にする

• 言語指定を変えて試す（ただし、チームルールで表記を固定する）

• 「色が付くこと」を前提に説明文を書かない（色に依存した説明は避ける）

たとえば「赤く表示される行を確認してください」のような説明は、色が付かない環境で破綻いたします。代わりに「3行目のserver:以下」など、位置やキー名で示す方が堅牢です。

同じMarkdownなのに環境で見え方が違う

Markdownは「同じ見た目になる」と期待されがちですが、実際には次の要因で差が出ます。

• 方言（実装の仕様差、拡張機能の有無）

• 自動整形（保存時に空白が変化する、タブがスペース化される等）

• CSSやテーマ（等幅フォントの見え方、余白、背景色など）

切り分けの手順は、次を推奨いたします。

1. 最小再現：問題のコードブロックだけを抜き出す（余計な文章や装飾を削る）

2. 境界確認：開始フェンス／終了フェンス、文字種、個数、前後空行を確認する

3. 入れ子確認：リスト・引用・表の中に入っていないか確認する

4. 環境確認：同じMarkdownを別環境（例：GitHub）で表示し、差分の方向性を把握する

5. 運用で吸収：環境差が避けられない場合、崩れにくい書き方（外に出す、入れ子をやめる）へ変更する

「正しい書き方」を追い求めるより、自組織の主要な閲覧環境で安定する書き方を標準化することが、最終的な解決になります。

Markdownのコードブロックの運用ルールとFAQ

チームで統一する推奨ルール

チームでの統一は、品質と保守性を大きく改善いたします。推奨ルールは、次のように少数精鋭にまとめるのが効果的です。

• コードブロックは原則フェンス形式に統一する

• フェンスはバッククォート3つに統一する（入力環境が厳しい場合はチルダに統一）

• フェンスの前後に空行を入れる

• リスト内コードブロックはテンプレを必須にする（インデントと空行）

• 言語指定は必須ケースのみ（JSON/YAML/bash/diff等）

• 危険コマンドは確認ステップを分離し、注意文をコードブロック外に書く

加えて、運用面では以下も有効です。

• よく使うコードブロックをスニペット化し、誰でも同じ形を貼れるようにする

• レビュー観点をチェックリストとしてPRテンプレに組み込む

• ドキュメント作成ガイド（1ページ）を整備し、例を添える

レビュー用チェックリスト

• フェンスの開始と終了が必ずペアになっている

• 開始と終了の文字種（バッククォート／チルダ）が一致している

• フェンスの行に余計な文字が入っていない（例：閉じフェンス後に説明文が続いていない）

• リスト内コードブロックは空行とインデントがテンプレどおりになっている

• コードブロックにプロンプト記号（$ 等）が混ざり、コピペ事故の原因になっていない

• プレースホルダが明確で、置換が必要な値が分かる

• 破壊的操作は確認ステップと分離され、注意文がある

• 言語指定が妥当で、表記揺れがない（チーム標準どおり）

このチェックリストは、全項目を毎回厳密に見るより、「崩れ」につながりやすい項目（フェンス、入れ子、プロンプト混入）」を重点的に見る運用が現実的です。

よくある質問

コードブロック内で太字やリンクを使えますか

基本的には使えません。コードブロック内は装飾が解釈されない前提であり、文字どおりに表示される設計です。強調が必要な場合は、コードブロックの外に説明文として太字やリンクを置いてください。たとえば「この行のserver:が重要です」のように、本文側で指示すると誤解が減ります。

バッククォートが入力できない場合はどうしますか

入力環境（キーボード配列、モバイル、IME設定等）により、バッククォートが打ちにくいケースがあります。その場合、チームとして チルダ（~~~）に統一するのは有効な回避策です。重要なのは「どちらを使うか」よりも「混在させないこと」です。混在するとフェンス不一致の事故が増えます。

フェンスが閉じられないときはどうなりますか

多くの環境では、終了フェンスが見つかるまでコードブロックが継続し、結果として「以降の文章がすべてコード表示」になります。まずは、終了フェンスが存在するか、開始と同じ文字種・同じ本数以上になっているかを確認してください。閉じフェンスの行に余計な文字が入っている場合もあるため、フェンス行は単独行にするのが安全です。

言語指定はMarkdownの標準機能ですか

一般に、言語指定は「Markdown処理系や表示環境が解釈してハイライトに使うことが多い」という位置づけです。したがって、必ずしも全環境で同じように効くものではありません。運用上は「色が付くと便利だが、色に依存した説明はしない」「色が付かなくても理解できるコード例にする」という方針が堅実です。

GitHubと社内ツールで表示が違うのはなぜですか

Markdownの実装仕様や拡張機能、テーマ（CSS）、入れ子解釈の差などが要因となります。まずは最小例で再現できるかを確認し、差が避けられない場合は「入れ子を浅くする」「引用内にコードを入れない」「テンプレに寄せる」といった、崩れにくい表現へ寄せるのが現実的です。

まとめ

Markdownのコードブロックは、次の方針で運用すると安定いたします。

• 新規ドキュメントでは、フェンス形式に統一する

• フェンスは「開始と終了をセット」「同じ文字種」「前後に空行」を徹底する

• 崩れやすいのは、閉じ忘れと入れ子（リスト・引用）であるため、テンプレで吸収する

• 言語指定は便利ですが環境差があるため、色に依存しない説明にする

• チーム運用では、少数のルールとチェックリストでレビュー品質を上げる

最後に、Markdownの表示挙動はツール更新や設定変更で変わる場合があります。表示が変わったときは「最小再現→境界確認→入れ子確認→運用で吸収」の順に切り分け、ルールやテンプレを更新してください。これにより、ドキュメントの保守性と事故耐性が継続的に高まります。