先に要点
- MDX は `Markdown(`MD』)に JSX(`X』)を埋め込めるようにした拡張』。`普通の Markdown 記法』 と `React コンポーネント』 を同じファイルに混ぜて書けるのが特徴。
- 具体的には `# 見出し』 や `**太字**』 のような Markdown 記法に加え、`
』 のような JSX タグを差し込める。記事の中に動くコンポーネントを置ける。 - 主な用途は ` 技術ドキュメント・ブログ・教材・製品 LP・コンポーネントカタログ』。Next.js / Astro / Docusaurus / Storybook など、現代の主要フレームワークが標準サポートしている。
- 万能ではない。` 大量の記事を非エンジニアが書く CMS』には向かない(JSX を書くのが前提のため)。`書き手がコードを書ける / 書く気がある』 かが採用判断の中心になる。
MDX ってよく聞くけど、普通の Markdown とどう違うの？ Next.js のブログで使うって聞いたけど、CMS の代わりになる？』 Storybook で MDX を見るけどなぜ？』 ── 現代の Web 開発でドキュメントやブログを扱うと、ほぼ必ず MDX の名前に出会います。
ざっくり言うと、MDX は Markdown の中に JSX(React コンポーネント)を書けるようにする仕組み』</strong> です。普通の Markdown で書く文章の途中に、<Chart />』 <Demo />』 のような動くコンポーネントを混ぜられる』 のが核心で、静的なドキュメント』 とインタラクティブな UI』 の境界を曖昧にする 役割を担います。
この記事では、2026年5月時点の MDX 3 系をベースに、何ができるか・Markdown との違い・どう使うか・採用判断軸 を整理します。 仕様は活発に変化しているので、最終確認は 公式ドキュメント も合わせて見てください。
MDX の基本 — Markdown + JSX
最小例を見ます。
# Vercel の料金体系
Vercel の料金は、ざっくり次の3軸で考えると分かりやすいです。
<PricingTable plans={["Hobby", "Pro", "Enterprise"]} />
特に **Pro** プランは月額 $20 から始められます。
<Note>
Hobby は商用利用不可です。詳しくは [Hobby と商用利用の境界](/articles/is-vercel-hobby-ok-for-commercial-use) を参照してください。
</Note>
詳細な料金は公式の <a href="https://vercel.com/pricing">Pricing ページ</a> を確認してください。
このファイルが MDX としてビルドされると:
# Vercel の料金体系』 →Vercel の料金体系
』- `<PricingTable />』 → React コンポーネントとして実行
- `<Note>...</Note>』 → カスタムコンポーネントとして展開
**Pro**』 →Pro』
という形で、テキストの構造化』 と動くコンポーネント』 が1ファイルで両立 します。
表現力
` テキストでは表現しきれない部分(チャート、デモ、対話 UI)をコンポーネントで埋め込める』。`画像』 や `動画』 の代わりに `動くもの』 を埋められる。
`ドキュメントが、React のコンポーネントツリーになる』 という発想が MDX のコアです。
どんな場面で活きるか
MDX が特に光るユースケースを整理します。
①技術ドキュメント
API リファレンス、SDK の使い方、ライブラリのチュートリアル。`コード例 + 動くデモ + 説明テキスト』 を1ファイルにまとめられる。Stripe、Vercel、Cloudflare のドキュメントが代表例。
② 技術ブログ
個人ブログ / 企業ブログ。`コードシンタックスハイライト + 図表 + 注意ボックス』 を統一感のあるコンポーネントで管理しやすい。Vercel や Next.js 公式ブログでも採用。
③ 製品 LP / マーケサイト
` 製品紹介と動くデモを織り交ぜたい』 LP。マーケッターと開発者の中間地点で、`Markdown 部分はマーケ / コンポーネント部分は開発』 と作業分担できる。
④ 学習教材 / チュートリアル
` 説明 + 動くサンドボックス』 を一体で提供したい教材。Astro Tutorial / Svelte Tutorial / React Learn など、教育系で広く使われる。
⑤ コンポーネントカタログ
Storybook の `MDX Stories』 で、コンポーネントの解説と実演を一体化できる。デザインシステムのドキュメント化で定番。
⑥ 仕様書 / 設計ドキュメント
` 仕様の中に動く UI モック / 図表 / チェックリスト』 を埋めたい場面。`Notion で書くと UI が固い』 系のチームに合う。
`書き手にコードの素養がある』 ことが前提になりますが、その代わり 記事と機能の境界を超えられる のが大きな利点です。
普通の Markdown / HTML との比較
Markdown だけで十分じゃない？ という疑問に対しては、表で並べると違いが見えます。
| 軸 | Markdown | HTML | MDX |
|---|---|---|---|
| 書きやすさ | 非常に高い | 低い(タグ多) | 高い(Markdown 部分 + 必要なときだけ JSX) |
| 動的要素 | × 静的のみ | ○ 別途 JS が必要 | ○ JSX で直接 |
| 共通コンポーネント | × 不可 | × | ○ Provider / カスタムタグで |
| GitHub プレビュー | ◎ | ○ | ○ 多くは表示される |
| CMS との統合 | ◎ | △ | △ JSX が壁になる |
| 非エンジニアが書く | ◎ | △ | × |
| 主な利用先 | README / 記事 / Wiki | サイト全般 | 技術ドキュメント / ブログ / カタログ |
`Markdown と HTML の中間の使いどころ』 にちょうどはまるのが MDX、と捉えると分かりやすいです。
Next.js / Astro / Docusaurus での扱い
MDX は主要フレームワークが標準サポートしているので、導入の手間はかなり小さいです。
` @next/mdx』 を入れると、`pages/blog/foo.mdx』 や `app/blog/foo/page.mdx』 がそのままページとして動く。`mdx-components.tsx』 で `見出しを自前コンポーネントに差し替え』 などが可能。
` @astrojs/mdx』 でサポート。`Content Collections』 と組み合わせると、`型付きの記事コレクション』 を MDX で扱える。技術ブログとの相性◎。
Docusaurus
Facebook 製のドキュメントフレームワーク。MDX が標準で、`バージョン管理 + 多言語 + 検索』 が組み込み。React 系プロジェクトの公式ドキュメントで広く採用。
Storybook
` MDX Stories』 でコンポーネントの解説 + 実演を一体化。`コンポーネントの使い方 = Storybook の MDX を読む』 のが、デザインシステム運用の現代的な定番。
新規プロジェクトで `ドキュメントを書きたい』 と思ったら、MDX 対応のフレームワークを選ぶのが結局いちばん楽、というのが2026年現在の景色です。
書き手の選び方 — エンジニア vs 非エンジニア
`MDX を採用すべきか』 で一番重要なのが、書き手が誰か です。
エンジニアが書く
技術ドキュメント、API リファレンス、内部 Wiki。`コードと隣接する場所で書く』 のが自然で、MDX のメリット最大。
技術系ライター
テックブログ、教育コンテンツ。`Markdown + 数個のカスタムコンポーネント』 程度を覚えれば書ける。MDX の用途として最適。
マーケ / コピーライター
` 純粋に文章だけ書きたい』 人には、MDX は重い。`
非エンジニア中心の記事制作
` 編集者が記事を量産する』 メディアサイトでは、MDX は不向き。Notion / Contentful / microCMS 等の CMS + ヘッドレス連携の方が合う。
`誰がコンテンツを書くか』 を最初に決め、それに合わせて MDX を選ぶか CMS を選ぶか判断するのが、運用後に後悔しない近道です。
どこで詰まりやすいか
便利な反面、踏みやすい注意点を整理します。
①JSX の構文ミスでビルドが落ちる
Markdown と違い、`タグの閉じ忘れ』 でビルドエラーになる。`記事を編集 → デプロイ失敗』 系の事故が起きやすい。`記事の差分は PR でレビュー + プレビュー確認』 がオススメ。
② 改行と JSX の関係
`
③ コンポーネントの提供方法
` MDX 内で使うコンポーネントをどこから渡すか』 を決める必要がある。`MDXProvider』 や `mdx-components.tsx』 などフレームワークごとに作法が違う。
④ 検索 / 全文検索
` JSX 部分は検索インデックスに乗りにくい』。Algolia / Pagefind などの検索を入れるときは、`コンポーネントの中身も拾えるか』 を確認する必要がある。
`Markdown と同じ感覚で書いていると、たまに転ぶ』 という認識を持っておくと、運用時のストレスが減ります。
AI 時代の MDX 観
AI 連携の文脈で MDX が活きる場面もあります。
AI 出力 → MDX 化
` AI が出した記事 + 図表コンポーネント』 をそのまま MDX として保存できる。`動くデモ』 を入れた記事が、AI 駆動で量産しやすい。
プロンプトで構造を伝えやすい
`
RAG との相性
` ドキュメントから AI が回答を生成する』 RAG で、MDX 由来の構造化情報を活かしやすい。`コードブロック / Note / Steps』 などのコンポーネントが意味を持ったまま渡せる。
AI チャット応答の構造化
AI チャット応答を MDX として返し、`』 `
AI が書く時代』 に、MDX は <strong> 構造化されたコンテンツ』 と `動くコンポーネント』 を両立させる中継地点 として、地味に重要な役割を担います。
採用判断のチェックリスト
`MDX を採用するか別の選択肢にするか』 の判断材料を整理します。
`書き手 × 動的要素の必要性 × 運用フロー』 の3点で判断すれば、ほぼ正解にたどり着けます。
MDX に関するよくある質問
Q. MDX は普通の Markdown と互換性がありますか？
A. 大半の Markdown 記法はそのまま動きます』</strong>。# 見出し』 **太字**』 link』 \``コード```』 のような GFM の記法はそのまま使えます。HTML を埋め込む』 ような書き方は JSX として解釈されるため、属性の書き方(class』 → `className』 等)に注意が必要です。
Q. MDX で書いた記事は GitHub でプレビューできますか？
A. Markdown 部分は表示されますが、JSX タグは未解釈で表示される』</strong>のが基本です。コードフェンスでくくる』 MDX 用エディタ拡張を使う』 などで補えますが、GitHub の README として完璧に表示したい』 ユースケースには Markdown(`.md』)の方が向きます。
Q. MDX のスタイリングはどうしますか？
A. カスタムコンポーネントで差し替える』 のが基本です。mdx-components.tsx』 で h2』 を自前の <MyHeading>』 にマップする、code』 を <HighlightedCode>』 にマップする、といった置換ができます。Tailwind のプラグイン @tailwindcss/typography』』 で `prose』 クラスを当てるのも定番です。
Q. MDX で frontmatter は使えますか？
A. 使えます。---』 で囲った YAML frontmatter が標準サポートされ、title』 date』 tags』 などのメタ情報を記事先頭に書けます。Astro Content Collections』 や Next.js MDX』 で、frontmatter を型付きで取り出せるのが一般的です。
Q. SSG / SSR とどう組み合わせますか？
A. ビルド時に MDX を React コンポーネントに変換 → SSG / SSR で HTML を出力』</strong>が標準フローです。Next.js / Astro / Docusaurus どれもMDX をビルド時に処理』 する設計で、ランタイムでのオーバーヘッドはありません。
Q. MDX と Notion / WordPress を組み合わせられますか？
A. Notion / WordPress を CMS とする → API で本文を取得 → MDX として表示』</strong>のような統合も可能です。ただし、Notion で書いた本文をそのまま MDX として動かす』 のではなく、`変換ツールを噛ませる』 必要があります。シンプルさを優先するなら、MDX か CMS のどちらかに寄せるほうが運用が楽です。
Q. AI 出力を MDX に変換する場合の注意点は？
A. JSX タグの閉じ忘れ』 とエスケープが必要な文字』に注意します。AI に MDX 形式で出力して』 と指定するときは、サンプル MDX をプロンプトに含める』 と精度が上がります。出力後にビルドエラーチェックを通すフローを組むのが安全です。
参考リンク
- MDX: 公式サイト
- MDX Docs: Documentation
- Next.js: MDX サポート
- Astro: MDX integration
- Docusaurus: 公式
- Storybook: MDX format