マークダウン入門ナビ 
エンジニアが技術知見や開発ノウハウを発信する定番プラットフォーム 「Qiita（キータ）」 。Qiitaの記事作成では、標準的なマークダウン（Markdown）記法に加えて、技術ドキュメントを美しく整理するための 強力な独自拡張記法（Note警告ブロック、ファイル名付きコードブロック、diff差分ハイライト、数式TeX、Mermaid作図、Marpスライドなど） が多数用意されています。
しかし、いざQiitaで記事を書こうとすると 「Qiitaで黄色や赤色の警告メッセージ枠を出す書き方は？」「コードブロックにファイル名を付ける方法は？」「diff差分を言語ハイライト付きで色分け表示するには？」「Qiita マークダウンで文字色を変える裏ワザはある？」「ZennやGitHubとの記法チートシートや違いを知りたい」 と検索するエンジニアの方も多いのではないでしょうか。
そこで本記事では、Qiitaで使える すべての独自拡張記法から基本のマークダウン記法、Zenn・GitHubとの比較表、コピペしてすぐ使える実践コードスニペットまで を網羅した 「Qiita Markdown 記法チートシート（完全保存版）」 をお届けします！Qiitaでの執筆時やテンプレート作成の辞書・リファレンスとして、ぜひブックマークしてご活用ください。
📌 目次（クリックで該当箇所へジャンプ）
- 1. 【独自拡張】メッセージ / Noteブロック4種（警告・補足・注意・通常）
- 2. 【独自拡張】ファイル名付きコードブロック＆シンタックスハイライト
- 3. 【独自拡張】diff差分ハイライト（言語ハイライト併用テクニック）
- 4. 【文字装飾】Qiita Markdownでの文字色変更・マーカー・打消し・キーボード記法
- 5. 【独自拡張】アコーディオン折りたたみ（details / summary）
- 6. 【独自拡張】数式表示（TeX / LaTeX / KaTeX）
- 7. 【独自拡張】Mermaid作図（フローチャート・シーケンス図・ER図）
- 8. 【独自拡張】Marpスライドモードの書き方
- 9. 【徹底比較】Qiita vs Zenn vs GitHub 記法差異チートシート
- 10. 【基本記法】Qiita マークダウン標準記法クイックリファレンス
- 11. Qiitaでマークダウン記法が崩れる・反映されない時の原因と対処法
- 12. まとめ
1. 【独自拡張】メッセージ / Noteブロック4種（警告・補足・注意・通常）
Qiitaの記事内で最も目を引く装飾が、コラムや補足、警告・注意喚起を枠線付きで表示できる 「Note記法（メッセージブロック）」 です。:::note タイプ名 と ::: で文章を囲むことで、アイコン付きのカラーボックスを簡単に作成できます。
Noteブロックの種類と記述方法（全4種）
QiitaのNoteブロックには、用途に合わせて 4つのタイプ が用意されています。
| タイプ | 記法（開始タグ） | 枠色 / アイコン | 主な用途 |
|---|---|---|---|
| 補足 / 情報 | :::note info |
青（インフォメーション） | 前提知識、参考リンク、Tips |
| 警告 / 注意 | :::note warn |
黄 / オレンジ（警告） | 非推奨な方法、注意すべき落とし穴 |
| 重要 / 危険 | :::note alert |
赤（アラート） | データ削除リスク、重大なエラー回避 |
| 通常メッセージ | :::note（引数なし） |
グレー（標準） | 一般的なコラム、補足説明 |
コピペ用コードスニペット
:::note info
【補足】ここに青色のインフォメーションメッセージを記述します。
マークダウン記法（**太字** や [リンク](https://qiita.com)）もそのまま利用可能です。
:::
:::note warn
【警告】ここに黄色の警告メッセージを記述します。
バージョン依存の注意点などを記載するのに適しています。
:::
:::note alert
【重要・危険】ここに赤色のアラートメッセージを記述します。
本番環境でのコマンド実行時など、危険を伴う操作の前に警告を入れましょう。
:::
:::note
【通常】ここに標準のグレー枠メッセージを記述します。
:::
実際の表示イメージ再現
APIキーの発行手順や事前準備の詳細は公式ドキュメントを参照してください。
Node.js v16以下では動作しません。必ずv18以降をご利用ください。
このコマンドを実行するとDBの全データが消去されます。バックアップを必ず取得してください。
執筆時点での最新ライブラリ仕様に基づき解説しています。
💡 Noteブロック記述のコツ
:::noteの直後および:::の前後は 必ず改行 してください。- Noteブロックの内部には、箇条書きリスト、太字、インラインコード、リンクなどを自由に入れ込めます。
2. 【独自拡張】ファイル名付きコードブロック＆シンタックスハイライト
Qiitaでは、コードブロックの先頭に 「言語名:ファイル名」 を記述することで、コードブロック上部にファイル名タブを表示させる独自機能があります。
ファイル名付きコードブロックの書き方
バッククォート3つの後に 言語名:ファイル名 をコロン（:）で区切って記述します。
```python:main.py
def hello():
print("Hello, Qiita!")
if __name__ == "__main__":
hello()
```
表示イメージ再現
主要言語のシンタックスハイライト指定子一覧
| プログラミング言語 | 指定子（Identifier） | ファイル名付き記述例 |
|---|---|---|
| JavaScript / TypeScript | javascript / typescript（js / ts） |
```typescript:index.ts |
| Python | python（py） |
```python:app.py |
| Go | go |
```go:main.go |
| Rust | rust（rs） |
```rust:lib.rs |
| PHP | php |
```php:UserController.php |
| Ruby | ruby（rb） |
```ruby:config.rb |
| HTML / CSS / SCSS | html / css / scss |
```html:index.html |
| Shell / Bash | bash / sh / shell |
```bash:deploy.sh |
| SQL | sql |
```sql:schema.sql |
| JSON / YAML / TOML | json / yaml / toml |
```yaml:docker-compose.yml |
| Docker / Dockerfile | dockerfile / docker |
```dockerfile:Dockerfile |
3. 【独自拡張】diff差分ハイライト（言語ハイライト併用テクニック）
コードの修正前後やGitの変更点を分かりやすく伝えるために不可欠なのが 「diff差分表示」 です。Qiitaでは、行頭に +（追加＝緑ハイライト）または -（削除＝赤ハイライト）を付けることで差分を色分け表示できます。
1. 基本のdiff構文
```diff
- const oldApiUrl = "https://api.example.com/v1";
+ const newApiUrl = "https://api.example.com/v2";
```
2. 【超便利】言語シンタックス＋diff＋ファイル名の併用構文
Qiita特有の強力な拡張として、 「diff_言語名:ファイル名」 と指定することで、 プログラミング言語の構文ハイライトを維持したまま、diffの追加・削除の色分けも同時に適用 させることができます。
```diff_javascript:config.js
const config = {
env: "production",
- timeout: 3000,
+ timeout: 5000,
+ retryCount: 3,
};
```
表示イメージ再現
指定形式は diff_python:test.py、diff_ruby:routes.rb、diff_php:index.php のように、diff_ の後ろに対象言語を指定します。Qiitaでプルリクエストの解説やコードレビュー記事を書く際に絶大な効果を発揮します。
4. 【文字装飾】Qiita Markdownでの文字色変更・マーカー・打消し・キーボード記法
「Qiita マークダウンで文字色を変えたい」「文字をカラフルに強調したい」という場合の装飾テクニックです。
1. 文字色を変更する方法（HTMLタグ活用）
Qiitaのマークダウンパーサーでは一部のインラインHTMLタグが許可されているため、スタイルや <font> タグを使用して 任意の文字色（赤・青・緑・太字など） を適用できます。
<font color="red">赤色のテキスト</font>
<font color="#2563eb">カラーコード指定の青色テキスト</font>
<span style="color: green; font-weight: bold;">緑色かつ太字のテキスト</span>
実際の表示：
- 赤色のテキスト
- カラーコード指定の青色テキスト
- 緑色かつ太字のテキスト
⚠️ 文字色変更の注意点: 過度な色使いは可読性を損ねます。原則としてNoteブロック（:::note）を活用し、どうしても単語単位で色を変えて強調したい場合のみ最小限にとどめるのがプロエンジニアの執筆作法です。
2. 各種インライン装飾スニペット
| 装飾 | マークダウン記法 | 表示例 |
|---|---|---|
| 太字（Bold） | **重要なテキスト** |
重要なテキスト |
| 斜体（Italic） | *斜体テキスト* |
斜体テキスト |
| 打ち消し線（Strike） | ~~取り消しテキスト~~ |
|
| インラインコード | `const a = 1;` |
const a = 1; |
| キーボード入力（kbd） | <kbd>Ctrl</kbd> + <kbd>C</kbd> |
Ctrl + C |
| 蛍光ペン風マーカー | <mark>ハイライト文字</mark> |
ハイライト文字 |
5. 【独自拡張】アコーディオン折りたたみ（details / summary）
長いログ出力、詳細なコード全体、補足FAQなどを折りたたんでスッキリ見せるには、HTML5の <details> と <summary> タグを使用します。
折りたたみの書き方と「空行ルール」
<details><summary>ここをクリックしてエラーログ全体を展開</summary>
<!-- 💡 重要: summaryタグの直後に必ず「空行」を1行挟むこと！ -->
```bash
Error: Connection timeout at Database.connect (db.ts:42:15)
at async initServer (server.ts:18:5)
at async main (index.ts:8:3)
```
リストや **太字** などのマークダウン記法も空行があれば正常に解釈されます。
</details>
表示イメージ再現
▶ ここをクリックしてエラーログ全体を展開
Error: Connection timeout at Database.connect (db.ts:42:15)
at async initServer (server.ts:18:5)
at async main (index.ts:8:3)リストや 太字 などのマークダウン記法も空行があれば正常に解釈されます。
🚨 折りたたみ内でマークダウンが効かない原因！
<summary>...</summary> の直後に 空行を入れずに続けてマークダウンを書くと、HTMLとしてパースされずただの生テキストになってしまいます 。必ず空行を1行挿入してください。
6. 【独自拡張】数式表示（TeX / LaTeX / KaTeX）
機械学習、データサイエンス、アルゴリズム解説などで威力を発揮するのが、KaTeXエンジンによる TeX数式表示 です。
1. インライン数式（文中に埋め込む）
ドルマーク1つ（$ ... $）で数式を囲みます。
アインシュタインの特殊相対性理論の方程式は $E = mc^2$ です。
平均値 $mu = frac{1}{N} sum_{i=1}^{N} x_i$ を計算します。
2. ブロック数式（中央揃えで独立表示）
ドルマーク2つ（$$ ... $$）で囲みます。
$$
f(x) = int_{-infty}^{infty} hat{f}(xi),e^{2 pi i xi x},dxi
$$
$$
begin{pmatrix}
a & b \
c & d
end{pmatrix}
begin{pmatrix}
x \
y
end{pmatrix}
=
begin{pmatrix}
ax + by \
cx + dy
end{pmatrix}
$$
頻出TeXスニペット早見表
| 数式表現 | TeX記法 | 解説 |
|---|---|---|
| 分数 | frac{a}{b} |
分子 a、分母 b の分数 |
| 上付き・下付き | x^2_i |
指数（^）と添字（_） |
| 総和（シグマ） | sum_{i=1}^{n} i |
1からnまでの合計 |
| 積分 | int_{a}^{b} f(x) dx |
区間 a〜b の定積分 |
| 平方根（ルート） | sqrt{x^2 + y^2} |
平方根・立方根 |
| ギリシャ文字 | alpha, beta, theta, lambda, sigma, pi |
α, β, θ, λ, σ, π など |
7. 【独自拡張】Mermaid作図（フローチャート・シーケンス図・ER図）
Qiitaは作図ツール 「Mermaid（マーメイド）」 に標準対応しています。コードブロックの言語指定に mermaid と書くだけで、外部画像を用意することなく フローチャートやシーケンス図、ER図、Gitグラフ をテキストから直接レンダリングできます。
1. フローチャート（業務フロー・条件分岐）
```mermaid
flowchart TD
A[ユーザー操作] --> B{ログイン済み?}
B -- Yes --> C[ダッシュボード表示]
B -- No --> D[ログイン画面へリダイレクト]
D --> E[認証成功]
E --> C
```
2. シーケンス図（API通信・システム連携）
```mermaid
sequenceDiagram
autonumber
actor User as ユーザー
participant Client as フロントエンド
participant API as バックエンドAPI
participant DB as データベース
User->>Client: ボタンをクリック
Client->>API: POST /api/v1/posts
API->>DB: INSERT INTO posts
DB-->>API: 登録完了 (ID: 123)
API-->>Client: 201 Created
Client-->>User: 完了トースト表示
```
3. ER図（データベース設計）
```mermaid
erDiagram
USERS ||--o{ POSTS : "1対多で所有"
POSTS ||--|{ COMMENTS : "1対多で紐付け"
USERS {
int id PK
string email
string name
datetime created_at
}
POSTS {
int id PK
int user_id FK
string title
text content
}
```
💡 Mermaidを活用するメリット: 仕様変更時もテキストを書き換えるだけで図が更新できるため、画像を作り直す手間が一切不要になります。
8. 【独自拡張】Marpスライドモードの書き方
Qiitaには、記事をそのまま プレゼンテーション用スライド として公開・表示できる「Marp（マープ）」機能が搭載されています。
スライドモードの書き方
記事の冒頭（Front-matter）に marp: true を宣言し、各スライドの区切りとして ---（ハイフン3つ）を配置します。
---
marp: true
theme: default
paginate: true
size: 16:9
---
# 🚀 Qiitaでスライドを作る方法
## 〜マークダウンで爆速スライド作成〜
**発表者:** @username
**日付:** 2026-09-02
---
# 📌 アジェンダ
1. なぜマークダウンでスライドを作るのか？
2. Qiita Marpの基本設定
3. デザインカスタマイズ
4. まとめ
---
# 💡 ポイント1: コピペで簡単
- `marp: true` を先頭に書くだけ
- `---` で次のスライドへ分割
- コードブロックや数式、Mermaidもそのまま動く！
```python
print("スライド内でもコードハイライト可能！")
```
スライドモードで投稿すると、読者はキーボードの矢印キーでスライドをめくりながら閲覧でき、勉強会やLT（ライトニングトーク）の資料公開に最適です。
9. 【徹底比較】Qiita vs Zenn vs GitHub 記法差異チートシート
「Qiita」「Zenn」「GitHub」の主要3プラットフォームにおけるマークダウン拡張仕様の違いを一覧表で比較しました。プラットフォーム間の転載やエディタの切り替え時にご活用ください。
| 機能 / 記法 | Qiita（キータ） | Zenn（ゼン） | GitHub（GFM） |
|---|---|---|---|
| メッセージ / 警告枠 | :::note info/warn/alert |
:::message / :::message alert |
> [!NOTE] / > [!WARNING] |
| コードブロックのファイル名 | ```言語:ファイル名 |
```言語:ファイル名 |
❌ 非対応（コメント等で代用） |
| diff＋言語ハイライト | ⭕ ```diff_python:file.py |
❌ ```diff のみ |
❌ ```diff のみ |
| 折りたたみ（details） | <details><summary> タグ |
:::details タイトル |
<details><summary> タグ |
| TeX数式 | ⭕ $ ... $ / $$ ... $$ |
⭕ $ ... $ / $$ ... $$ |
⭕ $ ... $ / $$ ... $$ |
| Mermaid作図 | ⭕ ```mermaid |
⭕ ```mermaid |
⭕ ```mermaid |
| スライドモード | ⭕ Marp（marp: true） |
❌ 非対応 | ❌ 非対応 |
| タスクリスト | - [ ] / - [x] |
- [ ] / - [x] |
- [ ] / - [x]（Issue操作可） |
| リンク自動カード化 | URLを独立行に配置 | URLを独立行に配置 | ❌ 通常リンクのみ |
※GitHubのマークダウン記法についてさらに詳しく知りたい方は、別記事「GitHub Markdown（GFM）記法完全ガイド」や「Markdownチェックボックスの書き方ガイド」もあわせてご覧ください。
10. 【基本記法】Qiita マークダウン標準記法クイックリファレンス
Qiita上で日常的に使う標準マークダウン記法のコピペ用チートシートです。
1. 見出し（Headers）
# 見出し1（記事タイトルレベル / 本文では非推奨）
## 見出し2（大見出し・セクション区切り）
### 見出し3（中見出し・小項目）
#### 見出し4（小見出し）
2. 箇条書き・番号付きリスト・チェックボックス
- リスト項目1
- リスト項目2
- ネスト（半角スペース2個または4個でインデント）
- ネスト項目
1. 番号付きリスト1
2. 番号付きリスト2
3. 番号付きリスト3
- [ ] 未完了タスク
- [x] 完了タスク
3. テーブル（表組み）
| 左寄せ | 中央揃え | 右寄せ |
| :--- | :---: | ---: |
| テキスト | テキスト | 1,000円 |
| 項目A | 項目B | 2,500円 |
4. 引用（Blockquote）
> これは引用文です。
> 複数行の引用も可能です。
>
> > 二重引用（ネスト引用）は `>>` を使用します。
5. リンク・画像・水平線
[Qiita公式サイト](https://qiita.com)
[Qiita公式サイト](https://qiita.com "ツールチップタイトル")
<img src="https://example.com/image.png" width="400" alt="画像説明">
---
11. Qiitaでマークダウン記法が崩れる・反映されない時の原因と対処法
Qiitaのエディタで「プレビューで装飾が崩れる」「Noteブロックが正しく表示されない」といったトラブルが発生した際は、以下の チェックリスト を確認してください。
🔍 記法トラブル解決チェックリスト
- 1. 空行が抜けていないか？
見出し、リスト、テーブル、コードブロック、:::note、<details>の前後には 必ず空行（Enter 1行） を入れてください。Markdownパーサーの誤作動の9割は空行不足が原因です。 - 2. 全角スペースが混入していないか？
リストのインデントやコードブロック指定子に全角スペース（ - 3.
:::noteや:::の閉じタグを忘れていないか？
Noteブロックは末尾の:::を忘れると、それ以降の本文すべてがメッセージ枠に吸い込まれてしまいます。 - 4. 太字の前後にスペースが入っているか？
日本語文字と**太字**が密着していると、正しく太字化されない場合があります。これは **重要** ですのように前後に半角スペースを空けると確実にパースされます。
12. まとめ
Qiitaのマークダウン記法は、基本構文を押さえるだけでなく、 Note警告ブロック、ファイル名付きコード、diff_言語指定、Mermaid作図、Marpスライド といった独自拡張を使いこなすことで、記事の「見やすさ」「伝わりやすさ」が何倍にも向上します。
📌 Qiita記法チートシートの最重要ポイントまとめ
- 補足・警告は
:::note info/warn/alertを使い分ける - コードブロックは
```言語:ファイル名でファイル名を表示 - 修正差分は
```diff_言語名:ファイル名で言語ハイライトとdiffを両立 - フローや構成図は
```mermaidでテキストから自動作図 - 折りたたみ（
<details>）内は必ず直後に空行 を挿入する
技術記事は、内容の有益さはもちろんのこと、読み手がストレスなく理解できる 「フォーマットの美しさ」 も評価（LGTMやストック数）を大きく左右します。ぜひこの記事をブックマークして、次回のQiita記事執筆に役立ててください！