Markdownコードブロック：構文、言語、例付きの完全ガイド

Markdown のフェンス付きコードブロックは、複数行のソースコードを格納できます。開始フェンスの後に続くトークンは言語タグであり、そのタグで何をハイライト表示するかはレンダラー側で決定されます。

本ガイドは、2026年のドキュメント作成ツール：Markdown、LaTeX、PDFと印刷ワークフロー の一部です。

GitHub は、Linguist および languages.yml 内のキーワードを使用して言語タグを照会します。Hugo 0.164 は、同じタグを Chroma に渡します。Chroma が認識していないタグであっても、そのブロックはコードブロックとして扱われ、プレーンテキストとして表示されます。見出し、テーブル、その他のブロックタイプは、Markdown チートシート に記載されています。

Markdown コードブロックの概要

Markdown には、コードを示すための3つの方法があります。インラインコードは段落内のスパンです。インデントブロックとフェンス付きブロックはどちらも複数行であり、言語タグを持つのはフェンス付きブロックのみです。

インデントブロックには言語を指定できません。CommonMark では4スペースインデントされた行をコードとして扱い、ハイライターに照合する対象を与えないため、サンプルに色付けを行いたい場合はフェンス付きブロックを使用するのが適切な形式です。

フェンスとは、3つ以上のバッククォート（```）またはティルダ（~~~）の行で始まり、コード、そして同じ文字で同じ長さ以上の閉じ行で終わるものです。閉じ行には情報文字列はありません。サンプル内で3バッククォートのフェンスを表示するには、4つのバッククォートで開始および終了してください。GitHub のコードブロックのドキュメントでは、生ファイルの読みやすさを高めるために、フェンスの前後に空行を置いているよう求めています。ただし、その空行がなくてもフェンスは解析されます。

以下のソースを Markdown として保存した場合：

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

この Hugo サイトでは以下のようにレンダリングされます：

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

インラインコードも、より小さな規模で同じバッククォートのルールを使用します。git status のような短いスパンには、単一バッククォートのペアが十分です。スパン自体がバッククォートを含む場合は、両側に2つのバッククォートを使用します：

`` `code` ``

Diff 構文のハイライト

diff とタグ付けられたフェンスは、変更内容をテキストとして表示する方法です。Hugo の Chroma レクサーは diff と udiff を受け入れます。GitHub も、その言語リストから同じ識別子をハイライト表示します。

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

- で始まる行には削除スタイルが、+ で始まる行には挿入スタイルが適用されます。どのプレフィックスも付いていない行は、そのレクサーにおいては通常のテキストです。色付けは行全体に行われます。行の中間に変更された単語は、単独ではマークされません。

言語識別子

情報文字列の最初の単語が言語です。Hugo のドキュメントでは、その単語は大文字小文字を区別しないとされています。Chroma にその言語のレクサーがない場合、Hugo 0.164 はハイライトラッパーなしでプレーンの <pre><code class="language-…"> を出力します。notalang のローカルレンダリングではそのように出力されました。guessSyntax はデフォルトで false であり、Hugo のドキュメントによると自動検出を実装しているのは5つのレクサーのみであるため、タグが省略された場合は推測された言語ではなくプレーンテキストのままになります。

これらのフェンスから生成される HTML は、クラス language-python と同じトークンを使用します。このクラスは、ハイライトされたページを Markdown に変換する際にコンバーターが保持すべきものであり、これは Python による HTML から Markdown への変換 で扱われるマッピングです。

以下の識別子は、Hugo の Chroma テーブルにそれらの言語として記載されているものです。Hugo 0.164 のレンダリングでは、公開されているテーブルに csharp、yaml、md と印刷されている箇所でも、cs、yml、markdown は色付けされました。

Jekyll 経由で引き続きハイライト表示を行う GitHub Pages サイトには、識別子が小文字である必要があります。GitHub 独自のドキュメントは、github.com のレンダリングとは別に、この要件を述べています。

GitHub は、一部のフェンスを色付きソースではなく図表として扱います：mermaid、geojson、topojson、stl。Hugo の Chroma テーブルには mermaid は記載されていません。Hugo サイトでは、レンダリングフック、ショートコード、またはスクリプトがそれを描画するまで、フェンスはソーステキストのままです。そのセットアップについては、Mermaid 図解クイックスタートとチートシート を参照してください。

ファイル名の指定

CommonMark や GitHub のコードブロックのドキュメントには、情報文字列をファイル名に変換する仕組みはありません。Hugo のハイライトオプションは、{linenos=inline} のような波括弧のペアです。ファイル名のフィールドは含まれていません。

言語の後のコロン

一部のジェネレーターは、js:app.js を言語と名前の組み合わせとして扱います：

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

GitHub はそうしません。Hugo 0.164 は、トークン全体をコード要素のクラス（language-js:app.js）として保持し、ファイル名を表示しません。最初の単語を超えて意味が追加されるのはどのダイアレクトかという比較については、GFM vs CommonMark vs Pandoc Markdown を参照してください。

フェンスの上の名前

フェンスの上の太字インラインコードの行は、GitHub、このサイト、および他の CommonMark レンダラーで名前を表示します：

**`app.js`**

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

見出しでも同じように機能します：

#### `app.js`

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

サンプル内部の名前

最初の行にあるコメントは、誰かがブロックをコピーしたときにコードと一緒に持ち運ばれます：

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

バッククォートのエスケープ

外側に4つのバッククォートを使用すると、3バッククォートのフェンスが表示され、これは Markdown を文書化するためのページのパターンです：

````markdown
```python
# この3バッククォートのフェンスは4バッククォートのフェンス内部です
print("hello")
```
````

閉じフェンスは、開始フェンスと同じ文字であり、少なくとも同じ長さでなければなりません。短い閉じフェンスはブロックを早期に終了させ、サンプルの残りが通常の段落として残ります。

Hugo のハイライトオプション

このサイトの config.toml には [markup.highlight] ブロックがないため、Hugo のデフォルトが適用されます：フェンス付きブロックはハイライト表示され、スタイルは monokai、スタイルはインラインで書かれ（noClasses が true）、行番号はオフです。Hugo 0.164 は、言語のみを要求するフェンス（上記の Python サンプルなど）も色付けします。

行番号と強調表示行は、言語の後の波括弧オプションです。このフェンスはインライン番号を要求し、2行目をマークしています：

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

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

linenos は inline、table、true、false を受け取ります。hl_lines は行番号または範囲のリストです。linenostart は表示される最初の番号を設定します。同じキーは大文字小文字を区別しません。highlight ショートコードはそれらを1つの引用付文字列として受け取り、その文字列は Hugo 0.164 でもまだ行番号をレンダリングしました：

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

色をスタイルシートに移動するには、noClasses を false に設定し、CSS を生成します。Hugo 0.164 は、そのコマンドで --mode と --modeSelector を受け入れます：

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector は、.dark .chroma のようなトップレベルのクラスの下に各ルールをスコープします。フラグの一覧は hugo gen chromastyles --help です。

フェンスが正しく見えない場合

サンプルを変更する前に、生成された要素を確認してください。この Hugo バージョンでは、既知の言語は div.highlight であり、そのコード要素には識別子が設定された data-lang が設定されています。不明な識別子は、class="language-…" を持つベア（素の）pre と code であり、notalang が生成したものです。

名前の app.js が欠落しており、クラスが language-js:app.js である場合、コロン形式が使用されました。名前をフェンスの上の行に移動してください。

チュートリアル自身のフェンスが散在した段落として表示される場合、外側のフェンスが内側のフェンスと同じ長さです。外側のフェンスを長くしてください。

短いコマンドが文の中間のバッククォートを飲み込んでしまう場合、スパンには、それを含む文字よりも長いバッククォートのペアが必要です。

役立つリンク

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/