Markdownコードブロック：構文、言語、および例を完全解説

ここでは、Markdownのコードブロックオプション、すなわちプログラミング言語の指定方法、diffフォーマット、およびコードブロックのファイル名の指定方法についてレビューします。

このガイドは、2026年のドキュメントツール：Markdown、LaTeX、PDFおよび印刷ワークフロー ハブの一部です。

Markdownコードブロックの概要

Markdownコードブロックは、Markdownドキュメント内でコードまたは事前フォーマットされたテキストを表示し、フォーマットを保持しつつ、オプションでシンタックスハイライトを有効にします。Markdownにおけるコードフォーマットには主に2つの種類があります：インラインコードとコードブロックです。

Markdownコードブロックの種類

主な違い

• インラインコードは単一のバックチック（`）を使用し、文内の短いコード用です。
• インデントされたコードブロックは、各行の先頭に4つのスペースまたはタブを使用します。シンタックスハイライトをサポートしておらず、現代的なMarkdownでは一般的ではありません。
• フェンスコードブロックは、コードの前後にトリプルバックチック（```）またはチルダ（~~~）を使用します。これは推奨される方法であり、特にGitHubなどのプラットフォームで以下の理由から採用されています：
  • 読み書きが容易です。
  • 開始バックチックの直後にプログラミング言語を指定することで、シンタックスハイライトを有効にできます。
  • フォーマットを保持し、複数行のコードをサポートします。

シンタックスハイライト付きフェンスコードブロックの例：

以下のようなMarkdownフォーマットのテキストがある場合：

```python
def hello():
    print("Hello, world!")
```

レンダリングされた出力は以下のようになります：

def hello():
    print("Hello, world!")

Markdownコードブロックのベストプラクティス

• フェンスコードブロック（トリプルバックチック）を使用して複数行のコードを表示し、プラットフォーム間の明瞭性と互換性を確保します。
• シンタックスハイライトのために、開始バックチックの後に言語を指定します（例：```python）。
• テキスト内の短いスニペットやコマンドにはインラインコードを使用します。
• シンタックスハイライトをサポートしておらず、読みやすさが低下するため、レガシー互換性が必須でない限りインデントされたコードブロックは避けます。
• 生のMarkdownでの読みやすさを向上させるため、フェンスコードブロックの前後には空白行を配置します。

特殊機能

• 一部のプラットフォームでは、コード変更を表示するためのdiffなどの追加言語識別子をサポートしており、コードレビューで追加または削除された行をハイライトします。
• コードブロック内でバックチックを表示するには、より多くのバックチックでブロックを囲みます（例：内部の3つのバックチックを表示するために4つのバックチックを使用）。

クイックリファレンスサマリー

最高の読みやすさとシンタックスハイライトを得るためには、フェンスコードブロックに言語識別子を指定してください。インラインコードは短いスニペットに予約し、互換性が必須でない限りインデントブロックは避けます。

コードブロックは、Markdownのテーブル と組み合わせることで、構造化された技術ドキュメントを作成するのに自然に適合します。

Diffシンタックスハイライト

Diffシンタックスハイライトを使用すると、コードの変更を明確に表示できます。これはドキュメント、コードレビュー、技術ブログで役立ちます。

• ブロックの開始と終了には、トリプルバックチック（```）を使用するフェンスコードブロックを使用します。
• 開始バックチックの直後に**diffを言語識別子として指定**します。

例：

- 削除される古い行
+ 追加される新しい行
  変更のない行

• -で始まる行は削除としてハイライトされます（通常は赤）。
• +で始まる行は追加としてハイライトされます（通常は緑）。
• プレフィックスのない行は特別にハイライトされません。

ベストプラクティス：

• 生のMarkdownでの読みやすさを向上させるため、コードブロックの前後に空白行を配置します。
• diffハイライトは、先頭文字に基づいて行全体にのみ色を付け、行内のインライン変更をハイライトしないことに注意してください。

ヒント： DiffハイライトはGitHub、GitLab、およびほとんどのMarkdownレンダラーで広くサポートされており、コード変更を伝えるための信頼性の高い選択肢です。

シンタックスハイライト対応言語

サポートされる言語の正確なセットは、使用するレンダラーまたはプラットフォームに依存します。Markdownは言語識別子をレンダリングエンジンに渡し、エンジンが適切なシンタックスハイライトを適用します。これは、PythonでHTMLをMarkdownに変換する 際に重要となります。言語クラス属性（例：class="language-python"）を持つ<code>タグは、フェンスブロック内のこれらの識別子に直接マッピングされます。

主要プラットフォーム（GitHub、VS Code、Bitbucket、Docusaurus、ReadMe）で一般的にサポートされる言語：

• Web & スクリプティング： javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• プログラミング： python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• データ & クエリ： sql, r, matlab
• マークアップ & 設定： markdown, ini, toml, dockerfile, makefile
• 特殊： diff, mermaid, geojson, topojson, stl （GitHub上のダイアグラムとデータビジュアライゼーション用）— 特にmermaid識別子は、サポートされているプラットフォームで完全なダイアグラムレンダリングを有効にします。完全な構文リファレンスとHugoセットアップガイドについては、Mermaidダイアグラムクイックスタートとチートシート を参照してください。
• その他： jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme など多数

言語の指定方法：

```python
def hello():
    print("Hello, world!")
```

ほとんどのレンダラーでサポートされる言語識別子：

注： ほとんどのレンダラーは、言語名の大文字小文字を区別しません。サポートされていない識別子を使用すると、コードブロックはプレーンテキストとしてレンダリングされます。

サポートされる言語の完全リストの検索：

• GitHub： Linguist を使用し、数百の言語をサポートしています。
• VS Code & 多くのWebレンダラー： highlight.js または Pygments を使用しています—詳細なリストについてはそれぞれのドキュメントを参照してください。
• Bitbucket： CodeMirrorモード およびPygmentsレクサーを参照します。

Markdownコードブロックでのファイル名の指定

コードブロックと一緒にファイル名を表示することで、読者はスニペットがどのファイルに属するかを識別できます。サポートはプラットフォームによって異なります。

1. コードブロックラベル内のファイル名（メタ構文）

一部のMarkdownエンジン（特定の静的サイトジェネレーターやドキュメントプラットフォーム）では、言語の後にコロンで区切ってファイル名を付加するメタ構文をサポートしています：

```js:app.js
console.log("Hello, world!");
```

これにより、ファイル名がコードブロックの上または横に表示されます。このサイトのHugoレンダラーではサポートされていません：

console.log("Hello, world!");

注： これはGitHub Flavor Markdownではサポートされていません。

2. 手動のファイル名見出しまたはインラインコード

普遍的な互換性（GitHub、Stack Overflow、およびほとんどのMarkdownレンダラーを含む）のために、太字のインラインコードを使用してコードブロックの上にファイル名を配置します：

**`app.js`**

```js
console.log("Hello, world!");
```

または見出しを使用します：

#### `app.js`

```js
console.log("Hello, world!");
```

これはどこでも機能し、視覚的にファイル名をコードブロックに関連付けます。

3. コード内のコメントとしてファイル名

ファイル名をコードブロック自体内のコメントとして含めます：

```js
// app.js
console.log("Hello, world!");
```

これは、コードをコピーしたときにファイル名を表示したい場合に特に便利です。

互換性サマリー

最大限の互換性のためにコードブロックの上に太字のインラインコードを使用し、プラットフォーム間で共有する際の明瞭さのためにコード内のコメントを検討してください。

コードブロック内のバックチックのエスケープ

コードブロック内でバックチックフェンスを表示するには—例えば、Markdown自体に関するドキュメントを作成する場合—ブロックをより多くの数のバックチックでネストします：

````markdown
```python
# このトリプルバックチックフェンスは、4バックチックフェンスの中にある
print("hello")
```
````

外側のフェンスとして4つのバックチックを使用することで、内部にトリプルバックチックの例を表示できます。これはMarkdownチュートリアルやチートシートで便利です。

Hugo固有：Highlightショートコード

Hugoを使用している場合、ビルトインのhighlightショートコードは、プレーンなフェンスブロックよりも多くの制御を提供します。これには行番号とハイライトされた行が含まれます：

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

オプション：

• linenos=true — 行番号を表示
• hl_lines=2 4 — 2行目と4行目をハイライト
• linenostart=10 — 行番号を10から開始

これは、特定の行に注意を引きたいチュートリアルやドキュメントで特に便利です。より多くのフォーマット機能についてはMarkdownチートシートを、Hugoコマンドとテンプレートの広範なリファレンスについてはHugoチートシートを参照してください。

有用なリンク

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks