Markdown: Markdownコード構文とコードブロック

コードは技術文書の核心です。Markdownは、読者が読んで実行できるようにコードをエレガントに提示する方法を提供します。

1. 学習目標

インラインコードの構文とユースケース
フェンスコードブロックとシンタックスハイライト
コードブロックの正しい言語タグの記述
コードブロック内の特殊文字のエスケープと処理
リストや引用内へのコード埋め込み

2. ある開発者の実話

(1) 課題：読者がコピーしたコードがエラーを起こす

Ninaは技術ブログでPythonチュートリアルを公開していましたが、読者からコードをコピーして実行するとエラーになるという苦情が寄せられました。調査したところ、彼女のブログプラットフォームのコードブロックにはシンタックスハイライトがなく、カンマとピリオドが同じように見え、(を（（全角括弧）としてコピーする人もいました。さらに悪いことに、一部のコードブロックには言語ラベルがなく、コードが色分けなしで表示されていました。

(2) 解決策：コードブロックの書式を標準化する

Ninaは適切な言語タグ付きのフェンスコードブロックに切り替え、公開前にすべてのコードスニペットを実際の環境でテストしました。また、「コードをコピー」ボタンも追加しました。切り替え後、読者からのエラー報告は90%減少しました。彼女のブログは再現性の高いコードサンプルが評価され、複数の技術メディアから注目を集めました。

3. インラインコード

(1) 基本構文

単一のバッククォート`でテキストを囲むとインラインコードになります。

MARKDOWN

`print()`関数を使ってテキストを出力します。

ターミナルで`npm install express`を実行してください。

`<div>`タグはHTMLで最も基本的なコンテナです。

シーン	構文	効果
関数名	`calculateTotal()`関数を呼び出す	`calculateTotal()`関数を呼び出す
キーボードショートカット	`Ctrl+S`で保存	`Ctrl+S`で保存
ファイル名	`.env`ファイルを編集する	`.env`ファイルを編集する
コマンド	`git status`を実行	`git status`を実行

(2) インラインコード内の特殊文字

バッククォート自体を表示するには、ダブルバッククォートで囲みます。

MARKDOWN

バッククォート文字を表すには`` ` ``を使用します。

文中で`code`と`` `backtick` ``を一緒に使用します。

💡 ヒント： インラインコードは主に関数名、変数名、ファイルパス、キーボードショートカット、短いコマンドの参照に使用します。長いコードにはコードブロックを使用してください。

(1) ▶ サンプル：インラインコードの正しい使い方

TEXT 📖 参照専用

utils/helpers.pyファイル内にformat_date()関数が定義されています。
datetimeオブジェクトを渡すと、フォーマットされた文字列を返します。

F5キーを押してページを更新します。

💡 ヒント： インラインコード内のテキストはそのまま表示されます。**で囲んでも太字になりません。これにより、コードが記述どおりに正確に表示されます。

4. フェンスコードブロック

(1) 基本構文

トリプルバッククォート```でコードブロックを囲み、オプションでシンタックスハイライト用の言語タグを指定します。

MARKDOWN

```python
def greet(name):
    return f"こんにちは、{name}さん！"

print(greet("太郎"))
```

⚠️ 注意： コードブロックの前後には空行が必要です。そうしないと、一部のパーサーが正しく認識できない場合があります。これはドキュメント作成時によく見落とされるルールの一つです。

(2) 言語タグの役割

タグ	言語	ファイル名の例
`python`	Python	`main.py`
`javascript`	JavaScript	`app.js`
`html`	HTML	`index.html`
`css`	CSS	`style.css`
`bash`	ターミナルコマンド	（なし）
`json`	JSON	`package.json`
`markdown`	Markdown	`README.md`
`text`	プレーンテキスト出力	（ハイライトなし）

PYTHON

# シンタックスハイライト付きのPythonコード
def fibonacci(n):
    """フィボナッチ数列のn番目の項を計算する"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))  # 出力: 55

5. インデントコードブロック

フェンスコードブロックに加えて、Markdownはインデントコードブロックもサポートしています。各行を4スペースまたは1タブでインデントします。

MARKDOWN

これは段落です。

    // 4スペースのインデントでこれがコードブロックになる
    function hello() {
        console.log("こんにちは！");
    }

通常のテキストに戻ります。

⚠️ 注意： インデントコードブロックはシンタックスハイライトをサポートせず、言語タグもありません。常にフェンスコードブロック（```）を優先してください。より強力で明確です。

(2) ▶ サンプル：フェンスコードブロックとインデントコードブロックの比較

TEXT 📖 参照専用

フェンスコードブロックはトリプルバッククォートを使用し、言語タグとシンタックスハイライトをサポートします。
インデントコードブロックは行頭に4スペースを使用し、互換性は高いですがシンタックスハイライトはありません。
可能な限りフェンスコードブロックを使用してください。

6. コードブロック内の特殊処理

(1) コードブロック内のバッククォートのエスケープ

コード自体にトリプルバッククォートが含まれる場合は、より多くのバッククォートで囲みます。

MARKDOWN

````text
```python
print("こんにちは")
```
````

💡 ヒント： 外側の囲みには````（4つのバッククォート）を使用するため、内側の```はプレーンテキストとして表示されます。

(2) 長いコード行の折り返し

MARKDOWN

# 推奨：各行を80文字以内に収める
const result = await api.getUserData(userId)
  .then(data => processData(data))
  .catch(error => handleError(error));

# 非推奨：折り返さない超長い行
const result = await api.getUserData(userId).then(data => processData(data)).catch(error => handleError(error));

(3) ▶ サンプル：コードブロックのよくあるエラーマーカー

TEXT 📖 参照専用

❌ 間違った方法：
言語タグのないコードブロックは白背景に黒文字で表示されます

✅ 正しい方法：
python言語タグ付きのコードブロックはカラフルなシンタックスハイライトを表示します

⚠️ 注意： 言語タグのないコードブロックはPrism.jsなどのシンタックスハイライターに無視され、白背景に黒文字で表示されます。読みづらくなります。

7. リストと引用内へのコード埋め込み

(1) リスト内のコードブロック

リスト内のコードブロックには、さらに8スペース（または2タブ）のインデントが必要です。

MARKDOWN

- テストを実行する：

        npm test -- --coverage

- フォーマットを確認する：

        npx eslint src/ --fix

💡 ヒント： リスト内でフェンスコードブロックを使用することもできますが、コードブロックの前後に空行が必要で、インデントを揃える必要があります。

(2) 引用内のコードブロック

MARKDOWN

> **主要な実装：**
>
> ```python
> def process_data(df):
>     return df.dropna().groupby("category").sum()
> ```
>
> 上記のコードはnull値をクリーンアップし、その後カテゴリ別にグループ化して集計します。

8. 完全な例：コードドキュメントページ

TEXT 📖 参照専用

データ処理スクリプトの概要

依存関係のインストール： pip install pandas numpy matplotlib

load_data()関数：CSVファイルからデータを読み込む
clean_data()関数：null値と重複行を削除する

完全なワークフロー：
1. データ読み込み - load_data("sales.csv")
2. クリーンアップ - clean_data(data)
3. 統計出力 - 行数と列名を表示

期待される結果：コードと説明がスムーズに交互に配置され、正しい言語タグが付けられ、インラインコードとコードブロックの役割分担が明確な、クリーンな技術文書。

❓ よくある質問

Q インラインコードとコードブロックをどう使い分ければいいですか？

A 2〜3単語以下の場合はインラインコードを使用します。1行を超える場合はコードブロックを使用します。関数名、変数名、ファイル名、ショートカットはインラインコードに。複数行のプログラム、設定、コマンドはコードブロックに入れます。

Q コードブロックにシンタックスハイライトが表示されないのはなぜですか？

A 最も一般的な原因は言語タグの欠落です。コードブロックの開始行にpythonやjavascriptなどの言語名が付いているか確認してください。

Q コードブロック内でMarkdownの書式を使用できますか？

A いいえ。コードブロック内のすべては生テキストとして表示されます。アスタリスクは太字にならず、ハッシュ記号は見出しになりません。

Q コードブロック内でバッククォートを表示するには？

A 外側の囲みにより多くのバッククォートを使用します。例えば、3つのバッククォートを表示するには、4つのバッククォートで囲みます。

Q コードブロック内の先頭スペースは保持されますか？

A はい。コードブロック内のすべてのインデントは正確に保持されます。Python、YAMLなどの言語はインデントに依存しているため、これは意図的な動作です。

📖 まとめ

インラインコードは単一バッククォート、コードブロックはトリプルバッククォートを使用
シンタックスハイライトのためにコードブロックに必ず言語タグを付ける
インデントコードブロック（4スペース）は非推奨、フェンス形式を優先
リスト内のコードブロックには追加のインデントが必要
コードブロック内のバッククォートは、より多くのバッククォートで囲んでエスケープ
コードブロック内のすべてのインデントと空白は完全に保持される

📝 練習問題

初級： 3つのインラインコードスニペット（ファイル名、関数名、キーボードショートカット）と、言語タグ付きのコードブロック1つを含むMarkdownセクションを書いてください。
中級： Markdown文書内にネスト構造を作成してください。箇条書き項目内にコードブロックを埋め込み、さらに引用内にもコードブロックを埋め込んでください。
発展： 3階層のバッククォートネストを持つMarkdownセクションを書いてください（コードブロックの表示方法を示すコードブロック自体を表示する方法をデモします）。外側の囲みに4つのバッククォートを使用し、正しくレンダリングされることを確認してください。

Web-Tutorial 技術チーム

複数の開発者によって共同維持されているプログラミングチュートリアルプラットフォーム。各チュートリアルは専門分野の開発者が執筆・レビューしています。正確で信頼性の高いコンテンツを目指しています — 問題を見つけた場合はお知らせください。

私たちについて