先に要点
- 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 コンポーネント)を書けるようにする仕組み です。 `普通の 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)をコンポーネントで埋め込める」。「画像」 や 「動画」 の代わりに 「動くもの」 を埋められる。
コンポーネントのスタイル
Markdown の HTML 要素(「
」 「
」 「」 等)を カスタムコンポーネントに差し替えられる。「
」 を 「」 にする、など。
「ドキュメントが、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 は 「 構造化されたコンテンツ」 と 「動くコンポーネント」 を両立させる中継地点 として、地味に重要な役割を担います。
採用判断のチェックリスト
「MDX を採用するか別の選択肢にするか」 の判断材料を整理します。
「書き手 × 動的要素の必要性 × 運用フロー」 の3点で判断すれば、ほぼ正解にたどり着けます。
MDX に関するよくある質問
Q. MDX は普通の Markdown と互換性がありますか？
A. 大半の Markdown 記法はそのまま動きます。「# 見出し」 「太字」 「link」 \``コード```」 のような GFM の記法はそのまま使えます。「HTML を埋め込む」 ような書き方は JSX として解釈されるため、属性の書き方(「class」 → 「className」 等)に注意が必要です。
Q. MDX で書いた記事は GitHub でプレビューできますか？
A. Markdown 部分は表示されますが、JSX タグは未解釈で表示されるのが基本です。「コードフェンスでくくる」 「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 を出力が標準フローです。Next.js / Astro / Docusaurus どれも 「MDX をビルド時に処理」 する設計で、ランタイムでのオーバーヘッドはありません。
Q. MDX と Notion / WordPress を組み合わせられますか？
A. Notion / WordPress を CMS とする → API で本文を取得 → MDX として表示のような統合も可能です。ただし、「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