Markdownコードブロックの書き方完全ガイド｜シンタックスハイライト・言語指定一覧・インラインコードの使い分けまで徹底解説

Markdown（マークダウン）で技術ブログ、README、仕様書、プログラミング学習ノートを書く際に、絶対に欠かせないのが「Markdown コードブロック（markdown code block）」と「Markdown インラインコード（inline code）」です。

「マークダウン コードブロックでプログラムを綺麗に色分け（シンタックスハイライト）して表示したい」「バッククォート3つ（“`）と1つ（`）の使い分けが曖昧」「指定できる言語名の正しいスペルを知りたい」「QiitaやZennのようにファイル名を表示したり、コード内にバッククォートを含めてエスケープしたい」といった疑問や要望を持つ方は非常に多いのではないでしょうか。

Markdown コードブロックとMarkdown シンタックスハイライトを正しく使いこなすと、プログラムコードの可読性が飛躍的に向上し、誰にとっても読みやすく美しい技術文書を瞬時に作成できるようになります。

この記事では、コピペですぐに使える基本構文から、主要プログラミング言語の識別子一覧表（Web・バックエンド・インフラ・設定ファイル等）、マークダウン コードブロックとインラインコードの使い分け、ファイル名表示やdiff差分ハイライト、バッククォートのエスケープ技まで、網羅的かつ分かりやすく徹底解説します！

【早見表】Markdownコードブロック＆インラインコード 逆引きチートシート

まずは「今すぐ書き方を確認してコピーしたい」という方向けに、代表的なMarkdown コードブロック記法の早見表を用意しました。用途に合わせてコピーしてお使いください。

```
echo "Hello World"
```

```python
def greet(name):
    return f"Hello, {name}!"
```

~~~javascript
console.log("Hello");
~~~

```diff
- const oldVal = 1;
+ const newVal = 2;
```

````markdown
```html
Hello
```
````

Markdownコードブロックの基本記法（フェンス記法）

Markdown（マークダウン）で複数行にわたるプログラムコードやコマンドラインの出力結果を表示するには、「フェンスドコードブロック（Fenced Code Blocks / markdown code block）」を使用します。

1. バッククォート3つ（“`）で囲む書き方

マークダウン コードブロックを作成する最も標準的で広く使われている方法が、コードの開始行と終了行をバッククォート3つ（```）で挟むフェンス記法です。

キーボードのバッククォート入力方法は以下の通りです：

• 日本語JISキーボード（Mac）： Shift + @
• 日本語JISキーボード（Windows）： Shift + @ （または「@」のキーとShiftキーを同時押し）
• US配列キーボード： ` （キーボード左上、Tab または Esc の下にあるキー）

```
function sum(a, b) {
    return a + b;
}
console.log(sum(5, 3));
```

function sum(a, b) {
    return a + b;
}
console.log(sum(5, 3));

マークダウン コードブロックで囲んだ部分は、HTMLの <pre><code>...</code></pre> タグに変換され、インデント（半角スペースやタブ）や改行がそのまま等幅フォントで保持されます。

2. チルダ3つ（~~~）で囲む書き方

Markdownの標準仕様（CommonMark）では、バッククォートの代わりにチルダ3つ（~~~）でコードブロックを囲む記法も正式にサポートされています。

~~~
# チルダでも同様にコードブロックになります
name = "Alice"
print(f"Hello, {name}")
~~~

# チルダでも同様にコードブロックになります
name = "Alice"
print(f"Hello, {name}")

3. 【補足】インデント記法（スペース4個）との違い

初期のMarkdown（オリジナル仕様）では、行頭に「半角スペース4個」または「タブ1個」を挿入することでコードブロックにするインデント記法が存在しました。

現在では、GitHub Flavored Markdown（GFM）をはじめとするほぼすべての現代的なMarkdown環境でフェンス記法（```）が標準となっています。特別な理由がない限り、フェンス記法を使用しましょう。

シンタックスハイライト（言語指定）の書き方と言語一覧表

Markdown コードブロックの最大の魅力は、プログラミング言語ごとの構文に合わせてキーワードや変数、文字列、コメントを美しく色分けしてくれる「Markdown シンタックスハイライト（Syntax Highlighting）」機能です。

言語指定の基本構文

markdown シンタックスハイライトを有効にする方法は極めてシンプルです。開始バッククォート（```）の直後に、対象の言語識別子（小文字）をスペースを空けずに記述します。

```python
# ユーザー情報を処理する関数
def process_user(user_id: int, is_active: bool = True):
    if not is_active:
        return {"status": "inactive", "message": "User is disabled"}
    
    score = calculate_score(user_id)
    return {"status": "active", "score": score * 1.5}
```

# ユーザー情報を処理する関数
def process_user(user_id: int, is_active: bool = True):
    if not is_active:
        return {"status": "inactive", "message": "User is disabled"}
    
    score = calculate_score(user_id)
    return {"status": "active", "score": score * 1.5}

ブラウザやエディタ側のハイライター（Prism.js、Highlight.js、Shikiなど）がこの識別子を読み取り、予約語（def, if, return）や文字列、数値、コメントを自動的に識別してCSSクラスを付与します。

主要言語・設定ファイルの指定名（言語識別子）一覧表

よく使われるプログラミング言語、マークアップ言語、設定ファイル、インフラ構成ファイルの指定名（エイリアス含む）をジャンル別にまとめました。

1. Webフロントエンド・デザイン

2. バックエンド・システムプログラミング言語

3. シェル・インフラ・データベース・設定ファイル

4. ドキュメント・作図・その他

Markdown インラインコード（`code`）の使い方とコードブロックとの使い分け

Markdownには、複数行のコードブロックのほかに、文章の途中に埋め込んでコードや専門用語を装飾する「Markdown インラインコード（inline code）」が用意されています。

1. インラインコードの基本構文

Markdown インラインコードを作成するには、装飾したい単語やフレーズをバッククォート1つ（`）で左右から囲みます。

パッケージをインストールするには `npm install axios` を実行し、
`package.json` の `dependencies` に追加されたことを確認してください。

インラインコードで囲んだ部分は、HTMLの <code>...</code> タグに変換され、背景色や文字色が変化して視覚的に引き立ちます。

2. インラインコードを使うべき代表的な場面

文章内で以下のような要素が登場するときは、インラインコードで囲むことで読者の誤読を防ぎ、専門文書としての完成度が高まります。

• 変数名・関数名・クラス名： const userData, getUserInfo(), AuthService
• コマンド・CLIオプション： git commit -m "feat: add login", docker compose up -d, --save-dev
• ファイル名・ディレクトリパス： .env.local, /etc/nginx/nginx.conf, src/components/Header.tsx
• HTMLタグ・属性： <div>, <a href="...">, class="container"
• キーボードショートカット： Ctrl + C や Cmd + Shift + P
• APIエンドポイント・HTTPステータス： GET /api/v1/users, 404 Not Found, 200 OK
• 環境変数・設定キー： NODE_ENV=production, PORT=3000

3. コードブロックとインラインコードの比較・使い分け基準

【実践・応用テクニック】コードブロックをより便利に使いこなす技

ここからは、実際の開発現場や技術ブログ執筆で役立つ、一歩進んだMarkdown コードブロックの応用テクニックを紹介します。

1. コードブロックに「ファイル名・タイトル」を表示する方法

技術ドキュメントでは「どのファイルに書くコードなのか」を明示したい場面が頻繁にあります。プラットフォームごとの記法を把握しておきましょう。

プラットフォーム別のファイル名記法

• Qiita（キータ）： 言語名の後ろにコロン（:）でファイル名を記述

  ```python:app.py
  print("Qiitaスタイルのファイル名表示")
  ```

• Zenn（ゼン）： 言語名の後ろにコロン（:）または半角スペースでファイル名を記述

  ```typescript:src/index.ts
  console.log("Zennスタイルのファイル名表示");
  ```

• Docusaurus / Astro / VitePress / Nextra（MDX系）： title="ファイル名" 属性を付与

  ```javascript title="config.js"
  module.exports = { port: 8080 };
  ```

• GitHub / 標準Markdown（共通記法）： 標準構文にはファイル名機能がないため、コードブロックの直前に太字や引用、またはファイルパスを明記します。

  📁 **src/utils/math.ts**
  ```typescript
  export const add = (a: number, b: number) => a + b;
  ```

def authenticate(token: str) -> bool:
    return token == "secret-token"

2. コードブロック内にバッククォートを含めるエスケープ技

Markdown自体の書き方を解説するブログやREADMEを書く際、「コードブロックの中にバッククォート3つ（“`）をそのまま表示させたい」というケースがあります。

そのまま ``` を中に書くと、外側のコードブロックが意図せず途中で終了してしまいます。この問題を解決するルールは「外側のバッククォートの数を内側より多くする（4連バッククォートを使う）」ことです。

````markdown
以下のようにMarkdownコードブロックを記述します：

```python
print("Hello World")
```
````

以下のようにMarkdownコードブロックを記述します：

```python
print("Hello World")
```

内側に4連バッククォートを含めたい場合は、外側を5連バッククォート（`````）にすれば何段階でも安全にネストして表示できます。

3. インラインコード内にバッククォートを含めるエスケープ技

文中のインラインコード内でバッククォート記号そのものを表示したい場合は、「2つのバッククォート（``）で囲み、前後に半角スペースを1つ空ける」というルールを使います。

Markdownのインラインコードは `` `コード` `` のようにバッククォートで囲みます。
単体のバッククォート `` ` `` を表示することも可能です。

前後の半角スペースはレンダリング時に自動的に除去されるため、余分な空白が表示される心配はありません。

4. diff記法によるコード差分（追加・削除）のカラー強調

コードの修正前後やGitコミットの差分を解説する際は、言語指定に diff を指定するのが非常に効果的です。

```diff
  function calculateTotal(price, taxRate) {
-     return price * taxRate; // バグ：税額のみ返していた
+     return price * (1 + taxRate); // 修正：税込合計金額を返す
  }
```

  function calculateTotal(price, taxRate) {
-     return price * taxRate; // バグ：税額のみ返していた
+     return price * (1 + taxRate); // 修正：税込合計金額を返す
  }

行頭に半角マイナス（-）を置くと赤色（削除行）、半角プラス（+）を置くと緑色（追加行）としてハイライトされます。変更のない行は半角スペース2個を行頭に空けます。

5. 長いコードブロックを折りたたむ（<details> の併用）

行数が非常に長い設定ファイルやログ出力をドキュメントに掲載する場合、ページが縦に伸びすぎて読者の集中力を妨げてしまいます。そんな時はHTML5の <details> タグを使って折りたたみ（アコーディオン）にしましょう。

<details>
<summary>【クリックで展開】完全な設定ファイル（nginx.conf）を見る</summary>

```nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.html index.htm;
}
```

</details>

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.html index.htm;
}

コードブロックでよくあるトラブル・原因と解決策

Markdown コードブロックを扱う際によく遭遇する疑問やトラブルとその対処法をQ&A形式でまとめました。

Q1. 言語を指定したのにシンタックスハイライト（色）が付かないのはなぜ？

Q2. コード内のインデントや半角スペースが崩れてしまう

Q3. 行番号（Line Numbers）を表示させるにはどうすればいい？

Q4. コードブロックにワンクリック「コピーボタン」を付けたい

まとめ｜Markdownコードブロックをマスターして読みやすい技術文書を作ろう

今回は、Markdown コードブロック（フェンス記法）とMarkdown インラインコードの基本文法から、主要言語のシンタックスハイライト指定一覧、ファイル名表示、エスケープ技、diff差分ハイライトまで幅広く解説しました。

マークダウン コードブロックを適切に使い分けることで、あなたの書いた記事や技術ドキュメントは格段に見やすく、読者にとってストレスのない価値ある情報になります。ぜひ日々のドキュメント作成やブログ執筆で活用してみてください！