# Fumadocs MDX (the built-in content source): 快速入門
URL: /zh-TW/docs/mdx
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/index.zh-TW.mdx

認識 Fumadocs 的官方內容來源 Fumadocs MDX。

## 簡介 [#introduction]

Fumadocs MDX 是一個將內容轉換為型別安全資料的工具，類似於 Content Collections。

它並非完整的 CMS，而是專為 React 框架設計的內容處理層，可用來處理部落格文章及其他各類內容。

### 什麼是集合？ [#what-is-a-collection]

**集合 (Collection) **是指由特定類型檔案所組成的集合。您可以在應用程式中使用 [Macro API](/docs/mdx/macro) 定義集合：

```ts title="lib/source.ts"
import { defineDocs } from 'fumadocs-mdx/macro';
import { loader } from 'fumadocs-core/source';

const docs = defineDocs({
  dir: 'content/docs',
});

export const source = loader({
  baseUrl: '/docs',
  source: docs.toFumadocsSource(),
});
```

可用的集合：

<Tabs items={["doc","meta","docs"]}>
<Tab value="doc">
將 Markdown &amp; MDX 檔案編譯為 React 元件，並提供**目錄**等實用屬性。

```ts
import { defineCollections } from 'fumadocs-mdx/macro';

export const test = defineCollections({
  type: 'doc',
  dir: 'content/docs',
});
```
</Tab>

<Tab value="meta">
將 YAML/JSON 檔案轉換為資料陣列。

```ts
import { defineCollections } from 'fumadocs-mdx/macro';

export const test = defineCollections({
  type: 'meta',
  dir: 'content/docs',
});
```
</Tab>

<Tab value="docs">
結合 `meta` 與 `doc` 兩種集合，是 Fumadocs 必備的集合。

```ts
import { defineDocs } from 'fumadocs-mdx/macro';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    // `doc` 集合的選項
  },
  meta: {
    // `meta` 集合的選項
  },
});
```
</Tab>
</Tabs>

例如，`doc` 集合會轉換 `.md` 與 `.mdx` 檔案：

<Files>
<Folder name="folder" defaultOpen>
<File name="ui.md" />
</Folder>

<File name="hello.md" />

<File name="index.mdx" />

<File name="meta.json" aria-disabled />
</Files>

您也可以透過 [Config API](/docs/mdx/collections) 在 `source.config.ts` 中定義集合，這種方式會在 `.source` 底下產生進入點檔案。

## 安裝 [#installation]

在以下環境中設定 Fumadocs MDX：

<Cards>
<Card title="Next.js" href="/docs/mdx/next">
搭配 Next.js 使用 Fumadocs MDX。
</Card>

<Card title="Vite" href="/docs/mdx/vite">
搭配 Vite 使用 Fumadocs MDX。
</Card>

<Card title="執行階段載入器" href="/docs/mdx/loader">
在 JavaScript 執行環境中使用 Fumadocs MDX。
</Card>
</Cards>

## 常見問題 [#faq]

### 內建屬性 [#built-in-properties]

MDX 檔案預設會匯出以下屬性。

| 屬性                    | 說明              |
| --------------------- | --------------- |
| `frontmatter`         | frontmatter     |
| `toc`                 | 目錄              |
| `structuredData`      | 結構化資料，可用於實作搜尋功能 |
| `extractedReferences` | 用於分析 `hrefs` 參照 |

### 自訂 Frontmatter [#customize-frontmatter]

使用 [`schema`](/docs/mdx/collections#schema-1) 選項傳入驗證用的 schema，藉此驗證 frontmatter 並定義其輸出屬性。

MDX 頁面也可以[在程式碼中匯出 frontmatter](/docs/next/markdown#frontmatter)。匯出的內容會合併至 YAML frontmatter 並覆蓋其值，再由集合的 schema 驗證合併後的結果：

```mdx title="content/docs/index.mdx"
---
title: Introduction
---

import { version } from '../../package.json';

export const frontmatter = {
  description: `The docs of v${version}.`,
};
```

這個 export 會在建置時執行。它可以使用頁面的匯入，以及同一區塊中位於它之前的 export，但無法使用頁面的內容或元件。`staticParams` 仍須保留在 YAML frontmatter 中，因為載入器會在 export 執行之前就讀取它。

### 自訂編譯器 [#customize-compiler]

Fumadocs MDX 透過 [MDX Compiler](https://mdxjs.com/packages/mdx)，以 unified 將 MDX 檔案編譯為 JavaScript 檔案。

集合也可以改用 [Sätteri](/docs/mdx/mdx#satteri) 進行編譯。兩者都內建一套由外掛與設定組成的預設組合。

您可以在[全域設定](/docs/mdx/global#mdx-options)或[集合設定](/docs/mdx/collections#mdxoptions)中自訂編譯器。