【保存版】ZennのMarkdown記法完全チートシート｜独自メッセージ記法・数式・アコーディオン＆GitHub連携執筆術

日本のエンジニアコミュニティで爆発的な支持を集める技術情報発信プラットフォーム **「Zenn（ゼン）」** 。シンプルで洗練されたUI、GitHubリポジトリ連携によるローカル執筆、そして「本（Book）」を通じた技術知見の有料販売機能など、現代の開発者のワークフローに最適化された機能が数多く揃っています。

Zennの記事や本を執筆する上で欠かせないのが、標準Markdown（CommonMark）を拡張した **「Zenn独自のMarkdown記法」** です。メッセージブロック（:::message）やアコーディオン折りたたみ（:::details）、数式（KaTeX）、Mermaid作図、そしてコードブロックでのファイル名表示やdiff差分ハイライトなど、技術ドキュメントの見栄えと説得力を劇的に高める記法が豊富に用意されています。

しかし、いざ執筆を始めると **「Zennで黄色や赤色の警告枠はどうやって出すの？」「コードブロックにファイル名を付ける書き方は？」「数式やMermaidが正しくレンダリングされない原因は？」「Zenn CLIとGitHubリポジトリを連携してVS Codeで書く手順を知りたい」「Qiitaとの記法の違いは？」** といった疑問に直面することも多いはずです。

そこで本記事では、Zennで使える **すべての独自拡張記法から標準Markdown記法、Zenn CLI×GitHub連携のローカル執筆環境構築、Qiitaとの記法差異比較表、コピペして即座に使える実践コードスニペットまで** を網羅した **「Zenn Markdown記法完全チートシート（完全保存版）」** をお届けします！アドベントカレンダー執筆や日常のアウトプットの辞書として、ぜひブックマークしてご活用ください。

1. 【早見表】Zenn Markdown独自拡張・基本記法チートシート一覧

「今すぐ使える構文をコピペしたい！」という方のために、Zenn特有の独自拡張記法および頻出Markdown記法の **逆引きチートシート早見表** をファーストビュー直下に用意しました。コードスニペットをそのままコピーしてご利用ください。

2. Zenn特有の便利記法完全解説（コピペ用コードスニペット付）

Zennが多くのエンジニアに支持されている最大の要因は、読者の視認性を劇的に向上させる **3つの独自拡張記法（メッセージブロック・アコーディオン・リンクカード）** の存在です。それぞれの記法ルールと実践スニペットを詳しく見ていきましょう。

① メッセージブロック（:::message, :::message alert）の使い分け

記事の要点、Tips、環境の前提条件、あるいは重大なリスクを読者に強調したい場合に活用するのが **メッセージブロック** です。Zennではコロン3つのコンテナ構文（:::）を使用します。

Zennのメッセージブロックには **2種類のタイプ** が用意されています。

1. **通常メッセージ（:::message）** ：青色の枠線と背景。Tips、補足情報、参考ドキュメントへのリンク、推奨設定などに使用。
2. **警告メッセージ（:::message alert）** ：赤色の枠線と背景。破壊的変更（Breaking Changes）、データ削除コマンド、非推奨APIの利用など、重大な注意喚起に使用。

コピペ用コードスニペット

:::message
【補足】ここに青色の通常メッセージを記述します。
Markdownの **太字** や [リンク](https://zenn.dev)、`インラインコード` もそのまま使えます。
:::

:::message alert
【警告】ここに赤色のアラートメッセージを記述します。
このコマンドを実行すると既存のデータベースが初期化されます。本番環境では絶対に実行しないでください。
:::

表示イメージ再現

② アコーディオン・折りたたみ（:::details 続きを読む）の実装

長大なエラースタックトレース、ビルドログ、巨大なJSONレスポンス、あるいは解答・解説などをすっきり収納できるのが **アコーディオン（折りたたみ）機能** です。

HTMLの <details><summary> タグを手打ちする必要はなく、Zennでは :::details タイトル という直感的なコンテナ構文で記述できます。

コピペ用コードスニペット

:::details 🔍 エラースタックトレース全文を展開する（クリックで開閉）
```bash
Error: Cannot find module 'react-dom/client'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object. (/workspace/src/index.tsx:2:1)
```

このエラーは依存パッケージが正しくインストールされていない場合に発生します。
`npm install` を再実行して解決してください。
:::

表示イメージ再現

Error: Cannot find module 'react-dom/client'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)

スマートフォンでの閲覧時、画面の縦スクロールが長大になると読者の離脱率が跳ね上がります。50行を超えるログや設定ファイル全文は、必ずアコーディオン内に格納して本文のテンポを保つのがZennでの鉄則です。

③ リンクカード自動展開と埋め込み（X/Twitter, GitHub, CodePen）

Zennでは、URLの配置方法によって **「リッチなリンクカード」** と **「テキスト埋め込み」** を自動で判別・生成してくれます。

1. リッチリンクカードの自動展開

前後に空行を空け、 **URL単独の行** として記述すると、リンク先のタイトル・ディスクリプション・OGPサムネイル画像を含んだ美しいカード形式で展開されます。

前後の文章...

https://zenn.dev/zenn/articles/markdown-guide

後続の文章...

一方、文章の中でリンクを貼りたい場合は、標準Markdownの `[アンカーテキスト](URL)` 構文を使います。この場合はカード化されず、通常のインラインハイパーリンクとして表示されます。

2. 外部サービスのネイティブ埋め込み構文

Zennは開発者に人気の主要Webサービスを単独URL行で記述するだけで、インタラクティブなウィジェットとして直接埋め込むことができます。

iframeタグを自分で書く必要は一切なく、URLをそのまま貼り付けるだけで最適なアスペクト比でレスポンシブに表示されます。

3. 技術記事の見栄えを劇的に高める高度表現

Zennで多くの「いいね」を獲得し、読者からプロの技術記事として信頼されるために必須となる **3大高度表現（ファイル名＋diff、KaTeX数式、Mermaid図解）** の記法をマスターしましょう。

コードブロックのファイル名表示（language:filename）とdiff差分表示

読者が手元の環境でコードを試す際、「どのファイルを編集すればよいのか」が一目でわかることは極めて重要です。

1. ファイル名付きコードブロック

バッククォート3つの直後に `言語名:ファイル名` をコロン（`:`）で繋いで記述します。

```typescript:src/utils/format.ts
export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}
```

export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

2. diff差分表示と「言語ハイライト＋diff」の併用

コードの修正前後を明示する際は `diff` を指定し、行頭に `+`（追加＝緑ハイライト）または `-`（削除＝赤ハイライト）を付けます。

さらにZennでは、 **`diff 言語名:ファイル名` のように半角スペースで区切って指定する** ことで、言語のシンタックスハイライトとdiff差分表示を同時に適用できます！

```diff ts:src/config.ts
  export const appConfig = {
    env: "production",
-   timeout: 3000,
+   timeout: 5000,
+   retryCount: 3,
  };
```

  export const appConfig = {
    env: "production",
-   timeout: 3000,
+   timeout: 5000,
+   retryCount: 3,
  };

※Qiitaではアンダースコア（`diff_ts:config.ts`）ですが、 **Zennでは半角スペース（`diff ts:config.ts`）** で記述します。この違いは頻出の落とし穴ですので覚えておきましょう。

数式記法（KaTeXインライン $…$、ブロック $$…$$）

機械学習、データサイエンス、暗号理論、アルゴリズム解説などで必須となる数式描画。Zennでは世界標準の超高速数式レンダラー **「KaTeX」** を採用しており、LaTeX構文で記述できます。

• **インライン数式** ：ドルマーク1個（`$数式$`）で文章内に埋め込みます。
• **ブロック数式** ：ドルマーク2個（`$$…$$`）で独立した行に中央揃えで表示します。

コピペ用コードスニペット

オイラーの等式は $e^{i\pi} + 1 = 0$ です。

平均値 $\mu$ と標準偏差 $\sigma$ は以下の数式で定義されます。

$$
\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^{N} (x_i - \mu)^2}
$$

行列の積は以下のように表現できます。

$$
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix}
=
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}
$$

より詳細なギリシャ文字一覧や分数・微積分のTeX記法チートシートは、当サイトの別記事「【コピペで使える】Markdown数式の書き方完全ガイド」でも詳しく解説しています。

Mermaidによるフローチャート・シーケンス図の埋め込み

アーキテクチャ設計や処理の流れを伝える際、画像を外部ツール（draw.ioやFigma等）で作って貼ると、仕様変更時の修正が大変です。Zennではテキストだけで作図できる **「Mermaid（マーメイド）」** にネイティブ対応しています。

コードブロックの言語名に `mermaid` を指定するだけで、自動的に美しいSVGベクター画像が描画されます。

1. フローチャート（処理の流れ・条件分岐）

```mermaid
flowchart TD
    Start([リクエスト受信]) --> Auth{認証チェック}
    Auth -- 成功 --> Process[データ処理実行]
    Auth -- 失敗 --> Err[401 Unauthorized]
    Process --> Cache[(Redisキャッシュ更新)]
    Cache --> Finish([200 OKレスポンス返却])
```

2. シーケンス図（API連携・通信手順）

```mermaid
sequenceDiagram
    autonumber
    actor User as ユーザー
    participant Front as フロントエンド
    participant API as バックエンドAPI
    participant DB as データベース

    User->>Front: ログインボタンをクリック
    Front->>API: POST /api/login (ID/PW)
    API->>DB: ユーザーレコード照合
    DB-->>API: 認証OK
    API-->>Front: JWTトークン発行
    Front-->>User: マイページへ遷移
```

Mermaidのさらに詳しいダイアグラム種別（ガントチャート・クラス図・GitGraph等）については、「【コピペで動く】Markdown Mermaid記法の書き方チートシート」で徹底解説しています。

4. Zenn CLIとGitHubリポジトリ連携でローカル執筆環境を作る手順

Zennが多くの開発者を惹きつける最大の強みが、 **「Zenn CLI」を用いたGitHubリポジトリ連携** です。ブラウザのエディタではなく、使い慣れた **VS Code** 上で拡張機能やAI補完、Copilotを活用しながら執筆し、`git push` するだけで記事が自動公開される最強の開発フローを構築できます。

npm init zenn による初期セットアップとディレクトリ構成

まず、ローカルマシンにNode.js（v18以上推奨）がインストールされていることを確認し、執筆用ディレクトリを作成して初期化します。

# 1. 執筆専用のディレクトリを作成して移動
mkdir my-zenn-content
cd my-zenn-content

# 2. npmプロジェクトの初期化（package.json作成）
npm init -y

# 3. Zenn CLIのインストールとコンテンツ初期化
npm install zenn-cli
npx zenn init

コマンドを実行すると、ディレクトリ内に以下の構成が自動生成されます。

my-zenn-content/
├── .gitignore
├── README.md
├── package.json
├── articles/       # ← ここに記事のMarkdownファイル（.md）が格納される
├── books/          # ← ここに「本」のチャプターフォルダが格納される
└── package-lock.json

新しい記事を作成するコマンド

記事を新規作成する際は、以下のコマンドを実行します。

npx zenn new:article

`articles/` ディレクトリ配下にランダムな14桁のスラッグ名を持つファイル（例: `articles/a1b2c3d4e5f6g7.md`）が生成されます。ファイルの冒頭には以下のような **Front-matter（YAMLヘッダー）** が自動挿入されます。

---
title: "記事のタイトルをここに記述"
emoji: "🚀"
type: "tech" # tech: 技術記事 / idea: アイデア・ポエム
topics: ["zenn", "markdown", "github"]
published: false # false: 下書き / true: 公開
---

• **type** ：技術記事なら `tech` 、組織論やポエムなら `idea` を指定します。
• **topics** ：関連技術タグを小文字の配列で最大5個まで指定します。
• **published** ：執筆中は `false`（下書き）にしておき、公開するタイミングで `true` に切り替えます。

VS Codeでリアルタイムプレビューしながら書く快適ワークフロー

ローカル執筆の快適さを決定づけるのが、ローカルプレビューサーバーです。ターミナルで以下のコマンドを実行します。

npx zenn preview

ローカルサーバーが起動し、ブラウザで `http://localhost:8000` にアクセスすると、 **Zenn本番サイトと全く同一のデザイン・フォント・数式レンダリングでプレビュー画面が表示** されます。

さらにVS Codeを強化したい方は、当サイトの解説記事「VS CodeでMarkdownを書くならこれ！必須のおすすめ拡張機能7選」もあわせて参考にしてください。

Git push で自動デプロイ・公開する運用方法

作成した記事をZenn本番サイトへ反映させる手順は、エンジニアにとって最も親しみのある **Gitワークフロー** そのものです。

1. **GitHubにリポジトリを作成** ：GitHub上で空のリポジトリ（Public推奨、Privateも可）を作成します。
2. **Zennダッシュボードで連携認証** ：Zennのアカウント設定「GitHub連携」を開き、作成したリポジトリを選択してアクセス権を連携します。
3. **リモートへプッシュ** ：ローカルの変更をGitでコミットし、GitHubへプッシュします。

# リモートリポジトリの設定（初回のみ）
git remote add origin https://github.com/your-username/my-zenn-content.git
git branch -M main

# 変更をコミットしてプッシュ
git add .
git commit -m "feat: add zenn markdown cheatsheet article"
git push -u origin main

`published: true` に設定されている記事は、GitHubへの `push` が検知された瞬間にZenn側のWebhookが作動し、 **数十秒で本番サイトへ自動公開・更新** されます。Pull Requestを活用すれば、チーム内での相互レビューやAI校正を経てからマージ・公開するという本格的なCI/CD執筆運用も可能です。

5. QiitaとのMarkdown記法・仕様の違い比較表

国内で技術発信を行うエンジニアが必ず比較するのが **「Zenn」と「Qiita」の記法仕様** です。両プラットフォームは似ているようで、細部の記法や思想が異なります。下書きの移行やクロスポスト（同時投稿）で失敗しないための比較マトリクス表です。

Qiitaの詳しいMarkdown記法や独自Noteブロックの使い方は、当サイトの「【保存版】QiitaのMarkdown記法チートシート」で網羅解説しています。また、12月のアドベントカレンダーで読まれる構成設計やコピペ用テンプレートについては「アドベントカレンダーで読まれる技術記事の書き方」をあわせてご活用ください。

6. よくある質問（FAQ）

7. まとめ：Zenn Markdownをマスターして技術発信を加速しよう

ZennのMarkdown記法は、単なるテキスト装飾にとどまらず、 **「技術的な複雑さをいかに直感的・視覚的に読者へ伝えるか」** という開発者の課題を徹底的に解決してくれる強力なツールです。

技術記事のアウトプットは、エンジニアとしての知見の整理はもちろん、コミュニティへの貢献やキャリアの可能性を大きく広げてくれます。ぜひ本チートシートを手元に置いて、次回のZenn記事やアドベントカレンダー執筆に役立ててください！