Markdown チートシート: 実践的な速習ガイド

多くのドキュメントは、最初はアスタリスクとハッシュ記号がいくつかあるだけのプレーンテキストファイルから始まる。そのファイルはたいてい Markdown だ。Web 向け執筆の唯一の方法ではないが、README、イシュートラッカー、チャットボット、静的サイトのデフォルトになっている。なぜなら、レンダリングされる前のソースでも読めるからだ。

この記事は実践的な速習ガイドだ。10 分とテキストエディタがあれば十分。インストールは不要。

Markdown とは

Markdown は軽量なマークアップ構文だ。John Gruber が 2004 年にオリジナルの仕様を公開した際の目標は一つだけ、プレーンテキストで見た目がよく、きれいに HTML に変換できる形式にすることだった。それ以来、GitHub、Obsidian、Notion、多くの静的サイトジェネレーター、そしてほとんどの大規模言語モデルの出力の入力形式になった。

核心となるアイデアはシンプルだ。タグではなく句読点で構造を示す。

# これは見出し

これは段落。

- これはリスト項目
- これもリスト項目

パーサーがこれを HTML に変換する。パーサーごとに対応する拡張が異なるため、どの標準を使うかは重要だ。

Markdown の標準は重要

Markdown に唯一の公式標準は存在しない。Gruber のオリジナル仕様には隙間があり、異なるツールが互換性のない形でそれを埋めた。あるアプリで書いた表を別のアプリに貼り付けると壊れることもある。対象とする方言を把握しておくべきだ。

CommonMark。 2014 年に始まった厳密で十分にテストされた仕様。核心構文を正確に定義している。移植性を重視するなら CommonMark を使う。
GitHub Flavored Markdown（GFM）。 表、タスクリスト、取り消し線、フェンス付きコードブロック、自動リンクを追加している。GitHub の README や issue コメントで使われている。
Pandoc Markdown。 引用、脚注、定義リスト、上付き・下付き文字、数式を追加している。学術執筆で一般的だ。
Obsidian / Quarto / MDX。 ウィキリンク、コールアウト、実行可能なコードセル、埋め込みコンポーネントを追加している。強力だが移植性は低い。

日々の作業では GFM が最も安全だ。ツール間を移動する可能性のある長文ドキュメントでは、CommonMark に文書化された拡張セットを加える方がよい。

Markdown の基本

見出し

ハッシュ記号を 1 つから 6 つ使う。1 つが最も大きい。

# 見出し 1

## 見出し 2

### 見出し 3

段落と改行

段落は空行で区切る。行末にスペース 2 つかバックスラッシュを置くと強制改行になる。

これが最初の段落。

これが 2 番目の段落。

強調

_斜体_ または _斜体_
**太字** または **太字**
**_太字かつ斜体_**
~~取り消し線~~（GFM のみ）

リンクと画像

[リンクテキスト](https://example.com)
[タイトル付きリンク](https://example.com "タイトル")
![代替テキスト](https://example.com/image.png)

内部リンクには相対パスを使う。

[Markdown を PDF に変換](/tools/markdown-to-pdf)

コード

インラインコードはバッククォート 1 つで囲む: `console.log("hi")`。

コードブロックはバッククォート 3 つで囲む。

```python
def hello():
    return "hello"
```


開きのバッククォートの直後に言語識別子を追加すると、シンタックスハイライトが効く。

## よく使うテクニックと例

### 引用

```markdown
> これは引用です。
> 複数行にまたがります。

入れ子にもできる。

> 外側の引用
>
> > 入れ子の引用

水平線

---

ダッシュ、アスタリスク、アンダースコアを 3 つ以上、1 行に単独で置く。

タスクリスト

GFM はチェックボックスをサポートする。

- [x] 下書きを書く
- [ ] 表を確認する
- [ ] 記事を公開する

HTML では無効なチェックボックスとしてレンダリングされる。本物のフォーム入力の代わりにはならない。

エスケープ

Markdown 記号を文字通り表示したい場合は、前にバックスラッシュを置く。

\*斜体ではない\*
\# 見出しではない

上級テクニックと例

表

表は GFM の拡張であり、オリジナルの Markdown 仕様には含まれない。

| 機能         | CommonMark | GFM  |
| ------------ | ---------- | ---- |
| 表           | 非対応     | 対応 |
| タスクリスト | 非対応     | 対応 |

揃え方は任意だ。

| 左揃え | 中央揃え | 右揃え |
| :----- | :------: | -----: |
| A      |    B     |      C |

表はシンプルに保つ。入れ子の表、行の結合、列の結合は標準ではなく、しばしば失敗する。

脚注

Pandoc と一部の GFM パーサーが脚注をサポートする。

ここに陈述がある。[^1]

[^1]: これが脚注のテキストだ。

脚注を含む PDF をレンダリングする必要がある場合は、Pandoc スタイルの構文をサポートするコンバーターを使うか、手動で埋め込む。

数式

Pandoc と多くの最新エディタは LaTeX 数式をサポートする。

インライン数式: $E = mc^2$

ブロック数式:

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

数式のレンダリングはパーサーと出力形式に依存する。HTML では通常 MathJax か KaTeX が必要だ。PDF コンバーターには LaTeX バックエンドが必要なことが多い。

定義リスト

Pandoc のもう一つの拡張だ。

用語
: 用語の定義。

別の用語
: 別の定義。

Markdown 内の HTML

Markdown だけでは足りない場合、HTML を直接書ける。

<p style="color: red;">これは赤いテキストだ。</p>

これはレイアウト、埋め込み動画、Markdown がサポートしない属性に便利だ。ただし移植性は失われるため、控えめに使う。

Markdown を変換すべきタイミング

Markdown は執筆とバージョン管理に優れている。しかし、どのデバイスでも見た目を完全に一致させたい最終文書には向かない。そのためコンバーターが存在する。

Markdown の下書きを共有可能な PDF にしたい場合は、Markdown to PDF コンバーターを使う。ブラウザ内で動作するため、ファイルが外部に出ることはない。

PDF から編集可能な Markdown が必要な場合は、PDF to Markdown コンバーターを使う。サーバーにアップロードせずに見出し、リスト、段落を抽出する。