使用 MDX 打造互動式文件
· 閱讀時間約 2 分鐘
為什麼選擇 MDX？
當你需要說明重點提示、互動範例或分頁程式碼等更豐富的敘事方式時，可以在 Markdown 中混用 React 元件；而一般文字仍維持純 Markdown，兼顧易寫與彈性。
提示
讓 MDX 區塊維持精簡（建議 40 行內），並替所有媒體提供描述性的 alt 文字，方便後續翻譯與在地化。
分頁內容範例
- CLI 檢查清單
- TypeScript 筆記
- Example
- 下載最新範本並執行
npm install。 - 透過
npm run start在本機確認頁面載入正常。 - 將遇到的錯誤與重現步驟加到 issue 描述中。
- 先在 Markdown 定義所有可翻譯字串，再用 props 傳入 React 元件。
- 為 MDX 互動元件設計
Props型別，方便其他作者複用。 - 若多篇文章都用到相同邏輯，可移到
@site/src/components/匯入。
<Tabs groupId="language">
<TabItem value="checklist" label="CLI 檢查清單">
1. 下載最新範本並執行 `npm install`。
2. 透過 `npm run start` 在本機確認頁面載入正常。
3. 將遇到的錯誤與重現步驟加到 issue 描述中。
</TabItem>
<TabItem value="notes" label="TypeScript 筆記">
- 先在 Markdown 定義所有可翻譯字串，再用 props 傳入 React 元件。
- 為 MDX 互動元件設計 `Props` 型別，方便其他作者複用。
- 若多篇文章都用到相同邏輯，可移到 `@site/src/components/` 匯入。
</TabItem>
</Tabs>
可用的主題元件
Tabs與TabItem能在同一區塊切換語言或平台CodeBlock方便加上區塊標題或切成 live editorAdmonition與Details可凸顯警示或折疊補充說明