MarkdownはJohn Gruberによって2004年に、一つのエレガントな目標で作られました：自然に読めるプレーンテキストを書き、それをきれいなHTMLに変換する。20年後、それはあらゆるところにあります — GitHub READMEファイル、プルリクエストの説明、Slackメッセージ、Notionドキュメント、ブログ記事、AIチャットの応答。意識的に考えるかどうかにかかわらず、あなたはキャリアの残りの期間毎日使うツールの一つです。
Markdownとは実際に何か
Markdownは軽量で読みやすい構文が重ねられたプレーンテキストです。行の先頭にある # は <h1> になります。単語を **二重アスタリスク** で囲むと太字になります。バッククォートはインライン コード を生成します。中心的な設計哲学は、Markdownのソースがレンダリングされる前でも — そのままで 読めるべきだということです。*アスタリスクで強調を囲んだ*メールを書いたり、箇条書きのリストにダッシュを使ったりしたことがあれば、あなたはすでにMarkdownに非常に近いものを書いていました。
簡単な前後比較を示します。左のMarkdownが右のHTMLを生成します：
## Getting Started
Install the package with **npm**:
`npm install my-library`
Then import it in your project — see the [docs](https://example.com) for details.<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>上半分はあなたが書き、Markdownプロセッサーが下半分を生成します。その変換ステップは、エディタやCIパイプラインに組み込まれると見えなくなります。
コアシンタックス — すべてのフレーバーが共有する部分
どのMarkdownバリアントを使っていても、これらのビルディングブロックはどこでも機能します：
- 見出し —
# H1、## H2、### H3（最大6レベル） - 太字とイタリック —
**太字**、*イタリック*、***両方*** - リンク —
[リンクテキスト](https://url.com) - 画像 —
 - インラインコード —
`バッククォート`でスニペットを囲む；トリプルバッククォートでフェンスコードブロックを開く - ブロック引用 — 行を
>で始める - 順不同リスト —
-または*で始まる行 - 順序付きリスト —
1.、2.などで始まる行 - 水平線 — 3つ以上のダッシュ：
---
上記すべてを一緒に使った現実的なREADMEスニペットを示します：
# json-transform
> A zero-dependency library for transforming JSON structures.
## Installation
```bash
npm install json-transform
```
## Usage
```js
import { transform } from 'json-transform';
const result = transform(input, schema);
```
## Features
- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies
See the [full documentation](https://json-transform.dev/docs) for advanced options.
---
MIT Licenseフレーバー問題 — CommonMark、GFMとその他
ここに落とし穴があります：「Markdown」は一つのものではありません。Gruberの2004年の元の仕様は意図的に緩やかで、何年にもわたる非互換の実装をもたらしました。異なるパーサーがエッジケースを異なる方法で処理していました — ネストされたリスト、ブロック引用内の空白行、強調とリンクの優先順位。同じソースファイルが異なるツールで異なるようにレンダリングされていました。
CommonMark（2014年に開始）がこれを修正しました。GitHub、Stack Overflow、Redditなどの人々を含む開発者グループが、652の例のテストスイートですべてのエッジケースをカバーする厳格で曖昧さのない仕様を書きました。ほとんどの現代的なツールは現在CommonMarkをベースラインとして使用しています。
GitHubはその後CommonMarkを独自の追加機能で拡張し、GitHub Flavored Markdown (GFM)を公開しました。GFMはGitHubのREADME、issue、プルリクエストで書くものです。他の多くのツールもGFMの拡張を採用していますが、すべてではありません — そのためGitHubでレンダリングされるものが、あなたの静的サイトジェネレーターやノートアプリで同じようにレンダリングされない場合があります。あなたのツールがどのフレーバーをサポートしているかを知ることで、多くの頭を悩ませることを節約できます。
GitHub Flavored Markdownの拡張機能
GFMはCommonMarkの上に5つの機能を追加しており、GitHubおよびGFMスーパーセットをサポートするすべてのツールで常に使用します：
テーブル — セパレーター行のダッシュを含むパイプ区切りの列：
| Method | Returns | Mutates? |
|---------|---------------|----------|
| map() | new array | No |
| filter()| new array | No |
| sort() | same array | Yes |タスクリスト — issueとプルリクエストのチェックボックス：
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release取り消し線 — テキストを二重チルダで囲む：
~~deprecated API~~ — use `newMethod()` instead言語ヒント付きフェンスコードブロック — 開始バッククォートの後の言語識別子がシンタックスハイライトを有効にします：
```python
def parse_config(path: str) -> dict:
with open(path) as f:
return json.load(f)
```自動リンク — https://example.com のような裸のURLが [テキスト](url) 構文を必要とせずに自動的にクリック可能になります。これはissueのコメントでは便利ですが、リンクしたくないURLを貼り付けた場合は驚くかもしれません。
実際にMarkdownを使う場所
Markdownは、最初に出会ったほとんどの開発者が期待するよりも多くの場所に登場します：
- GitHubとGitLab — READMEファイル、issue、プルリクエストの説明、wiki、さらにはコミットメッセージの本文。触れるすべてのリポジトリには少なくともREADME.mdがあります。
- 静的サイトジェネレーター — Jekyll、Hugo、Eleventy、Astro、Next.jsはすべてMarkdownコンテンツファイルを受け入れます。
.mdファイルに投稿を書き、ジェネレーターがビルド時にHTMLページに変換します。 - ドキュメントツール — MkDocs、Docusaurus、GitBookはすべてMarkdownソースを中心に構築されています。オープンソースライブラリはほぼ普遍的にこれらのうちの一つを使用しています。
- ノートアプリ — Obsidian、Notion、Bear、TyporaはすべてネイティブフォーマットとしてMarkdownを使用しています（拡張機能はさまざま）。あなたのノートはポータブルなプレーンテキストファイルで、独自のデータベースではありません。
- CMSプラットフォーム — GhostはMarkdownをネイティブに使用しています。ContentfulとStrapiはどちらもMarkdownフィールドをサポートしています。ヘッドレスCMSのセットアップは通常、長文コンテンツをMarkdown文字列として保存します。
- AIツール — ChatGPTとClaudeはどちらもデフォルトでMarkdownを出力します。AIの応答のコードスニペット、太字の用語、箇条書きリストはMarkdownです — チャットUIはそれらをレンダリングしますが、基本的なテキストは
**太字**と```pythonです。
Markdown vs HTML — どちらをいつ使うか
MarkdownはHTMLに変換されますが、HTMLが表現できるすべてを表現できるわけではありません。<div class="card">、data-* 属性、または aria-* 属性に相当するものはありません。単純な散文コンテンツ — ドキュメント、README、ブログ記事、変更ログ — には、Markdownの方が書くのが速く、生の形式ではるかに読みやすいです。複雑なUIコンポーネント、カスタムレイアウト、または特定の属性を必要とするアクセシビリティの注釈には、HTMLが必要です。
良いニュース：ほとんどのMarkdownプロセッサーはインラインの生のHTMLを通過させます。両方を混在させることができます。<figcaption> 付きの <figure>、または <details> 開示ウィジェットが必要な場合は、.md ファイルに直接HTMLを書いてください。プロセッサーはそれをそのまま渡します。このエスケープハッチは控えめに使用してください — ファイルの3分の1以上が生のHTMLの場合、直接HTMLを書いて当サイトのHTMLフォーマッターを使ってきれいにした方がいいかもしれません。
- Markdownを使う場合：ドキュメント、README、変更ログ、ブログ記事、ナレッジベース記事、API説明フィールド
- HTMLを使う場合：正確なレイアウト、カスタムコンポーネント、フォーム、特定の属性を必要とする要素
- 両方を混在させる場合：主に散文コンテンツだが、いくつかの構造的な例外がある（レスポンシブテーブル、ビデオ埋め込み）
まとめ
Markdownは欺くほど単純に見えます — ほんのいくつかの句読点ルールのように見えますが、実質的にすべての主要なオープンソースプロジェクトのドキュメントを動かしています。コアシンタックスを理解するのに約10分かかります。フレーバーの違い（CommonMark vs GFM vs あなたのSSGが使うもの）を理解することが、ドキュメントツールと時々戦う開発者とそうでない開発者を分けるものです。
権威ある参照：標準化された仕様については CommonMark、GitHubの拡張については GitHub Flavored Markdown、実用的なチートシート参照については Markdown Guide。日常の執筆には、当サイトの Markdownプレビュー でレンダリングされた出力を即座に確認でき、Markdownフォーマッター でソースファイルの一貫性を保てます。