Markdownコードブロック：構文、言語と例を含む完全ガイド

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

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

Markdownコードブロックの概要

Markdownコードブロックは、Markdownドキュメント内でコードまたはプレフォーマットテキストを表示し、フォーマットを維持し、必要に応じて構文ハイライトを有効にします。Markdownには2つの主なコードフォーマットタイプがあります：インラインコードとコードブロック。

Markdownコードブロックのタイプ

主な違い

• インラインコードは単一のバックティック（`）を使用し、文脈内での短いコードに適しています。
• インデントコードブロックは各行の先頭に4つのスペースまたは1つのタブを使用します。構文ハイライトはサポートされておらず、現代的なMarkdownではあまり見られません。
• フェンスコードブロックは三つのバックティック（```）またはチルダ（~~~）で囲まれます。これは特にGitHubなどのプラットフォームで推奨される方法です。理由は以下の通りです：
  • 読み書きが簡単です。
  • 開いているバックティックの直後にプログラミング言語を指定して構文ハイライトが可能です。
  • フォーマットを維持し、複数行のコードをサポートします。

構文ハイライト付きフェンスコードブロックの例:

以下のMarkdown形式のテキストがある場合:

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

レンダリングされた出力は次のようになります:

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

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

• フェンスコードブロック（三つのバックティック）を使用して、複数行のコードを表示し、プラットフォーム間での互換性と明確性を確保してください。
• 開いているバックティックの直後に言語を指定して構文ハイライト（例: ```python）を有効にしてください。
• 短いスニペットや文脈内でのコマンドにはインラインコードを使用してください。
• インデントブロックは、レガシーコンパチビリティが必要な場合を除き避けてください。これらは構文ハイライトをサポートしておらず、読みにくくなる可能性があります。
• フェンスコードブロックの前後に空白行を配置して、生のMarkdownでの読みやすさを向上させてください。

特殊な機能

• 一部のプラットフォームは、diffなどの追加の言語識別子をサポートしており、コード変更を表示するために使用できます。これにより、コードレビューで追加または削除された行が強調表示されます。
• コードブロック内でバックティックを表示するには、ブロックをより多くのバックティックで囲む（例: 四つのバックティックで三つのバックティックを表示）必要があります。

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

フェンスコードブロックに言語識別子を使用して、読みやすさと構文ハイライトを最適化してください。インラインコードは短いスニペットに限定し、インデントブロックはコンパチビリティが必要な場合のみ使用してください。

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

差分構文ハイライト

差分構文ハイライトは、コード変更を明確に表示できるため、ドキュメンテーション、コードレビュー、技術ブログで非常に役立ちます。

• フェンスコードブロック（三つのバックティック）を使用してブロックを開始および終了してください。
• 開いているバックティックの直後に diff を言語識別子として指定してください。

例:

- old line that will be removed
+ new line that will be added
  unchanged line

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

ベストプラクティス:

• ブロックの前後に空白行を配置して、生のMarkdownでの読みやすさを向上させてください。
• 差分ハイライトは、行の先頭の文字に基づいて全体の行のみを色分けします。行内での変更はハイライトされません。

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

構文ハイライトでサポートされる言語

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

主要なプラットフォーム（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での図とデータ可視化に使用）
• その他: 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 および多くのウェブレンダラー: highlight.js または Pygmentsを使用します。詳細なリストについては、ドキュメントを参照してください。
• Bitbucket: CodeMirrorモードおよび Pygments レクサーを参照してください。

Markdownコードブロック内でファイル名を指定する

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

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

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

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

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

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

注意: GitHub風の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自体についてのドキュメント作成）は、ブロックをより多くのバックティックでネストしてください：

````markdown
```python
# この三バックティックのフェンスは四バックティックのフェンス内にあります
print("hello")
```
````

外側のフェンスに四つのバックティックを使用することで、三つのバックティックの例を表示できます。これは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