MDX 是什麼？把 Markdown 變成可互動的網頁內容

MDX 將 Markdown 與 JSX 結合，讓開發者可以直接在文章、文件與教學內容中，加入互動圖表、提示框、產品展示與自訂元件，同時保留 Markdown 容易閱讀與維護的特性。

過去在網站上撰寫文章時，開發者通常會使用 Markdown 管理內容。它非常適合編排標題、段落、清單與程式碼區塊，語法簡單，閱讀與版本管理也相對容易。不過，Markdown 主要用來呈現靜態內容。當文章需要加入互動圖表、分頁選單、產品展示或自訂提示框時，開發者往往得另外處理 HTML、JavaScript，甚至建立一套額外的元件系統。JSX 雖然能自由使用 React 元件，卻不適合直接撰寫大量長篇內容。原本簡單的一段文字，也需要放進標籤與元件結構中，不僅降低閱讀性，後續編輯與維護也更加麻煩。

MDX 嘗試解決的，正是 Markdown 與 JSX 之間的落差。

開發者可以繼續使用熟悉的 Markdown 撰寫大部分內容，只有在需要互動功能或特殊版面時，才插入 JSX 元件。如此一來，文章不再只是單純的文字檔，而能直接成為網站介面的一部分。

一、MDX 是什麼？

MDX 是一種將 Markdown 與 JSX 結合的內容格式。一般 Markdown 可以用井字號建立標題、用星號建立清單，也能插入連結、圖片與程式碼區塊。

MDX 保留了這些寫法，同時允許開發者：

• 匯入 React 或其他 JSX 元件
• 在文章中直接使用自訂元件
• 寫入 JavaScript 表達式
• 使用 import 與 export
• 將整份內容當成一個元件使用

例如普通的 Markdown 文章可能是：

# MDX 入門

這是一篇介紹 MDX 的文章。

## 為什麼使用 MDX？

因為 Markdown 很容易閱讀與維護。

改成 MDX 後，可以直接在文章裡加入元件：

import { Demo, Callout } from './components'

# MDX 入門

這是一篇介紹 MDX 的文章。

<Callout type="tip">
  Markdown 負責內容，元件負責互動。
</Callout>

<Demo />

標題與段落依然是 Markdown，只有提示框與互動展示使用 JSX。

簡單來說，MDX 就像是：

Markdown 負責寫內容，JSX 負責加入元件與互動功能。

二、真正特別的地方：文章裡的每個元素都能變成元件

MDX 最重要的特色，不只是能在 Markdown 中插入 JSX。

它也能改變 Markdown 原本的呈現方式。一般 Markdown 裡的標題，最後通常會被轉換成 <h1> 或 <h2>；連結會被轉換成 <a>，程式碼區塊則會轉換成 <pre> 與 <code>。

例如，可以把所有二級標題換成自己設計的標題元件：

const components = {
  h2: SectionTitle,
  a: CustomLink,
  code: CodeBlock
}

<Article components={components} />

設定完成後：

## 安裝方式

將 <h2>變成帶有編號、錨點、動畫或品牌樣式的 SectionTitle。

同樣的方式也可以用來：

• 自動美化所有程式碼區塊
• 替外部連結加入圖示
• 統一文章圖片的圓角與說明文字
• 為標題產生章節錨點
• 將引用文字改成品牌提示卡
• 讓表格支援排序與篩選

這代表內容作者只需要專心使用 Markdown，網站則能統一控制所有文章的視覺與互動方式。

三、除了元件，也能在內容裡使用資料與 JavaScript

MDX 也支援 JavaScript 表達式，以及 ESM 的 import 和 export 語法。

例如，可以先定義文章中的資料：

export const courseName = 'MDX 入門'
export const lessons = 6

# {courseName}

這堂課總共有 {lessons} 個單元。

匯入外部資料與元件：

import { PricingTable } from './pricing-table'
import plans from './plans.json'

# 方案比較

<PricingTable plans={plans} />

這讓內容不再只能顯示寫死的文字。開發者可以將元件、資料與文章放在一起，建立會隨資料變化的文件、產品說明或教學內容。同一個價格元件可以被放進多篇文章中；當方案資料更新時，所有引用它的頁面也能同步更新。

四、MDX 最後會被編譯成 JavaScript 元件

MDX 並不是瀏覽器可以直接理解的格式。在網站建置過程中，MDX 會先被編譯成 JavaScript，再交給 React、Preact、Vue 或其他支援 JSX 的環境執行。

例如下面這段 MDX：

export function Badge() {
  return <span>New</span>
}

# MDX 3 <Badge />

編譯後，概念上會變成一個可被網站載入的元件：

export default function MDXContent() {
  return (
    <h1>
      MDX 3 <Badge />
    </h1>
  )
}

因此，MDX 文件並不只是等待被解析的文字內容，而是一個完整的程式模組。

它可以：

• 被其他頁面匯入
• 接收 Props
• 使用自訂 Layout
• 匯出文章資訊
• 引用外部元件
• 與網站的設計系統整合

MDX 本身不需要在使用者開啟頁面後，才重新解析所有 Markdown。官方說明指出，MDX 會在建置階段完成編譯，輸出可以直接由 JSX Runtime 執行的 JavaScript。

五、MDX 不只適用於 React

雖然 MDX 最常與 React、Next.js 一起出現，但它並不限定只能用在 React 專案中。只要專案支援 JSX，就能根據使用的前端框架、建置工具與 JSX Runtime 選擇適合的整合方式。

MDX 支援的常見技術包括：

• 前端框架與 JSX Runtime：React、Preact、Vue、Solid、Svelte
• 應用程式框架：Next.js
• 建置工具：Vite、Rollup、webpack、esbuild
• 執行環境：Node.js、Bun

不同環境需要搭配不同的 MDX 套件：

• Next.js 或 webpack：使用 @mdx-js/loader
• Vite 或 Rollup：使用 @mdx-js/rollup
• esbuild 或 Bun：使用 @mdx-js/esbuild
• Node.js：使用 @mdx-js/node-loader
• 需要自行控制編譯流程：直接使用核心編譯器 @mdx-js/mdx

其中，@mdx-js/mdx 可以將 MDX 內容編譯成 JavaScript，也能直接執行編譯後的內容。相較於框架專用套件，它提供更底層且彈性的控制方式，適合自訂內容系統、文件平台或特殊的建置流程。目前官方的 @mdx-js/* 套件皆採用現代 JavaScript，並且只提供 ESM 模組。MDX 3 的最低執行環境為 Node.js 16，因此專案必須支援 ESM，並使用 Node.js 16 以上版本。

六、還能透過外掛擴充 Markdown 功能

MDX 預設支援的是標準 Markdown 語法。表格、刪除線、任務清單、數學公式、Frontmatter 與程式碼高亮等功能，則可以透過 remark 與 rehype 外掛加入。

常見的擴充方式包括：

• remark-gfm：加入表格、刪除線、任務清單與註腳
• remark-frontmatter：讀取 YAML 或其他 Frontmatter
• remark-math：解析數學公式
• rehype-katex：將公式渲染成 KaTeX
• 程式碼高亮外掛：替不同程式語言加入語法顏色

例如：

import { compile } from '@mdx-js/mdx'
import remarkGfm from 'remark-gfm'
import remarkMath from 'remark-math'
import rehypeKatex from 'rehype-katex'

const result = await compile(content, {
  remarkPlugins: [remarkGfm, remarkMath],
  rehypePlugins: [rehypeKatex]
})

MDX 的擴充方式可以分成三個層次：

1. 編譯器選項
2. remark、rehype 與 recma 外掛
3. 實際顯示內容的自訂元件

因此，開發者既可以改變文章如何被解析，也可以改變文章最後如何呈現在畫面上。

七、MDX 適合拿來做什麼？

MDX 最適合的並不是所有內容，而是需要同時兼顧「長篇文字」與「互動元件」的網站。

1. 技術文件

開發文件可以在說明文字中直接加入程式碼預覽、API 測試工具、參數表格與互動範例。

讀者不需要離開文件頁面，就能直接操作元件或查看執行結果。

2. 部落格與內容網站

一般文章可以繼續用 Markdown 編寫，遇到需要補充資訊時，再加入提示框、圖表、影片或產品展示元件。

這比將整篇文章寫成 JSX 更容易維護。

3. 線上課程與教學內容

教學文章可以加入測驗、程式碼編輯器、步驟導覽與完成進度。

原本只能閱讀的內容，也能變成可以實際操作的學習介面。

4. 簡報與互動式故事

MDX 也能用於簡報、研究文章與互動式敘事。每個章節可以保留 Markdown 的可讀性，同時加入圖表、動畫或自訂版型元件。

MDX 官方社群列出的應用案例，也包含 MDX 簡報、研究文章與文件框架等專案。

八、MDX 與 JSON 有什麼不同？

MDX 與 JSON 都能被程式讀取，但兩者解決的問題並不相同。

JSON 適合儲存結構化資料：

{
  "title": "MDX 入門",
  "sections": [
    {
      "type": "heading",
      "content": "什麼是 MDX？"
    },
    {
      "type": "paragraph",
      "content": "MDX 結合 Markdown 與 JSX。"
    }
  ]
}

當內容變得很長時，JSON 會出現大量欄位名稱、引號、括號與巢狀結構。直接閱讀或編輯時，通常比較不直覺。相同內容用 MDX 表示則是：

# MDX 入門

## 什麼是 MDX？

MDX 結合 Markdown 與 JSX。

JSON 的優勢是格式固定、容易驗證與交給程式處理；MDX 的優勢則是內容本身容易閱讀，而且可以直接插入元件。因此比較適合的分工是：

• JSON：儲存設定、狀態與結構化資料
• MDX：撰寫文章、文件、教學與需要元件的長篇內容

MDX 並不是要完全取代 JSON，而是提供一種更接近人類寫作方式的內容格式。

九、使用 MDX 前，需要注意哪些限制？

MDX 雖然保留了 Markdown 的寫作體驗，但它同時也是一種程式語言。

這讓它比普通 Markdown 更強大，也代表語法會更嚴格。

1. 部分 Markdown 寫法不同

MDX 使用 JSX 取代一般 HTML，因此 <img> 必須寫成自我關閉的 <img />。

未跳脫的 < 與 { 也可能被當成 JSX 標籤或 JavaScript 表達式。縮排式程式碼區塊與部分自動連結語法，同樣無法直接按照普通 Markdown 的方式使用。

2. 語法錯誤會造成編譯失敗

普通 Markdown 就算少打一個符號，通常仍能顯示部分內容。

但 MDX 混合了 JSX 與 JavaScript。如果元件標籤沒有正確關閉、括號不完整，或 import 語法錯誤，就可能直接造成編譯錯誤。

3. 不適合直接執行陌生使用者輸入

由於 MDX 可以包含 JavaScript 表達式、匯入模組與元件，官方將它視為程式語言，而不只是純文字格式。

如果網站允許陌生使用者直接提交並執行 MDX，可能產生安全風險。官方建議不要直接信任網路上任意來源的 MDX；若一定要執行，則必須另外處理 iframe、執行環境隔離、資源限制與程序終止等安全機制。

因此，MDX 比較適合由可信任的作者、內容團隊或版本控制系統管理，而不是直接當成一般使用者可以自由執行的輸入格式。對一般純文字文章來說，使用 Markdown 可能已經足夠。

但當內容需要加入互動展示、資料圖表、設計系統與可重複使用的元件時，MDX 就能讓文章從單純的文字檔，進一步變成網站產品的一部分。

資料來源

https://mdxjs.com/

https://mdxjs.com/docs/what-is-mdx/

https://mdxjs.com/docs/getting-started/

https://mdxjs.com/docs/using-mdx/

https://mdxjs.com/docs/extending-mdx/

https://mdxjs.com/docs/troubleshooting-mdx/

https://mdxjs.com/blog/v3/

https://mdxjs.com/community/projects/