跳至內容
Fumadocs

集合

應用程式的內容資料集合

定義集合

您可以定義集合來解析特定的一組檔案。本頁範例會在 source.config.ts 中定義集合，而 Macro API 則是在 lib/source.ts 中定義，兩者的選項大致相同。

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    // schema
  }),
  // 其他選項
});

type

集合可接受的類型。

import { defineCollections } from 'fumadocs-mdx/config';

// 僅掃描 meta 檔案
export const metaFiles = defineCollections({
  type: 'meta',
  // 選項
});

  • type: meta

    接受 JSON/YAML 檔案，以及具有預設匯出 (default export) 的程式碼模組 (meta.ts 或 meta.js) 。請參閱 Meta。可用選項：

    屬性

    型別

  • type: doc

    Markdown/MDX 文件。可用選項：

    屬性

    型別

schema

用來驗證檔案資料的 schema (doc 類型驗證的是 frontmatter，meta 類型驗證的是檔案內容) 。

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    name: z.string(),
  }),
});

支援與 Standard Schema 相容的函式庫，包括 Zod。

請注意，驗證是在建置時進行，因此輸出必須可序列化。 您也可以傳入一個函式，該函式會接收轉換上下文 (transform context) 。

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: (ctx) => {
    return z.object({
      name: z.string(),
      testPath: z.string().default(
        // 檔案的絕對路徑
        ctx.path,
      ),
    });
  },
});

mdxOptions

針對以 unified 編譯的集合，在集合層級自訂 MDX 選項。

此 API 僅適用於 doc 類型。

source.config.ts
import { defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  mdxOptions: {
    // MDX 選項
  },
});

這是刻意的設計：此設定會移除您的全域設定與 Fumadocs MDX 所套用的所有預設設定，讓您完全掌控 MDX 選項。

您可以使用 applyMdxPreset 套用預設的 MDX 設定組合。

source.config.ts
import { applyMdxPreset, defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  mdxOptions: applyMdxPreset({
    // 擴充預設組合
  }),
});

compiler

此 API 僅適用於 doc 類型。

改用 Sätteri 而非 unified 來編譯此集合，並改為傳入 satteriOptions 以取代 mdxOptions。

source.config.ts
import { defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  compiler: 'satteri',
  // 選用，預設為全域的 `satteriOptions`
  satteriOptions: {
    // Sätteri 選項
  },
});

與 mdxOptions 不同，除非您傳入 preset: 'minimal'，否則集合層級的 satteriOptions 仍會沿用內建的預設組合。此外，它會直接取代全域的 satteriOptions，而不會與其合併。

postprocess

此 API 僅適用於 doc 類型。

您可以使用 postprocess API 將建置階段的資訊傳遞至執行階段。

  • includeProcessedMarkdown

    匯出由 Remark LLMs 產生的文件 Markdown。可傳入 true 或其選項。

    import { defineDocs } from 'fumadocs-mdx/config';

export default defineDocs({
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});

    請使用 getText('processed') 讀取，例如透過 loader()：

    import { source } from '@/lib/source';

const page = source.getPage('...');
console.log(await page.data.getText('processed'));

  • valueToExport

    部分 remark 外掛會將輸出儲存在 vfile.data (編譯階段的記憶體) 中，您的程式碼無法存取這些資料。

    您可以指定要納入的屬性名稱，這些屬性會轉換為 ESM 匯出，讓您在匯入 MDX 檔案時即可存取。

    import { defineDocs } from 'fumadocs-mdx/config';

export default defineDocs({
  docs: {
    postprocess: {
      valueToExport: ['dataName'],
    },
  },
});

定義 Docs

為 Fumadocs 定義集合。

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: '/my/content/dir',
  docs: {
    // 選填，`doc` 集合的選項
  },
  meta: {
    // 選填，`meta` 集合的選項
  },
});

dir

請透過 defineDocs 自訂內容目錄，而不是在個別集合中分別設定：

import { defineDocs } from 'fumadocs-mdx/config';

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

schema

您可以擴充 docs 與 meta 預設的 Zod 4 schema。

import { defineDocs } from 'fumadocs-mdx/config';
import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
import { z } from 'zod';

export const docs = defineDocs({
  docs: {
    schema: pageSchema.extend({
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      // 其他屬性
    }),
  },
});

How is this guide?

最後更新於

本頁目錄

定義集合typeschemamdxOptionscompilerpostprocessincludeProcessedMarkdownvalueToExport定義 Docsdirschema
Sponsors
General TranslationGeneral TranslationFerry HealthFerry Healthassistant-uiassistant-uiInkeepInkeep