頁面 Slug 與頁面樹

概覽複製錨點連結

Fumadocs 會透過 loader() 從您的內容目錄產生頁面 slug 與頁面樹 (側邊欄項目) ， 路由功能則交由您的 React 框架處理。

您可以用類似檔案系統路由的方式定義資料夾與頁面。

若要進一步自訂輸出結果，可以使用載入器外掛。

檔案複製錨點連結

若是 MDX & Markdown 檔案，您可以透過 frontmatter 自訂頁面資訊。

---
title: My Page
description: Best document ever
icon: House
---

## Learn More

Fumadocs 會讀取以下屬性來建構頁面樹。

Slugs複製錨點連結

頁面的 slugs 是根據其檔案路徑產生的。

資料夾複製錨點連結

資料夾用來組織多個頁面，您可以建立 Meta 檔案 來自訂資料夾。

資料夾群組複製錨點連結

根據預設，將檔案放入資料夾會改變其 slugs。 若不想影響子檔案的 slugs，可以用括號包住資料夾名稱。

根資料夾複製錨點連結

將資料夾標記為根資料夾，僅顯示目前開啟的根資料夾中的項目。

{
  "title": "Name of Folder",
  "description": "The description of root folder (optional)",
  "root": true
}

例如，當您開啟根資料夾 framework 時，其他資料夾 (例如 headless) 就不會顯示在側邊欄和其他導覽元素中。

根類型複製錨點連結

root 也可以接受字串，用來指定根資料夾的類型： 在同一個上層範圍內，相同類型的根資料夾可以互相切換，例如同一份文件的不同版本。

{
  "title": "1.0.0",
  "root": "version"
}

root: true 其實就是預設類型，會以頁籤形式顯示。

切換到同類型的另一個根資料夾時，頁面會對應到其結構投影，也就是相對於根資料夾位於相同路徑的頁面：

Meta複製錨點連結

在資料夾中建立 meta.json 檔案，即可自訂該資料夾。

{
  "title": "Display Name",
  "icon": "MyIcon",
  "pages": ["index", "getting-started"],
  "defaultOpen": true
}

若您的內容來源支援，也可以用程式碼撰寫 meta 檔案 (meta.ts 或 meta.js) ，並將資料設為預設匯出 (default export) 。

頁面複製錨點連結

資料夾中的項目預設依字母順序排序，您可以使用 pages 新增項目或調整項目順序。

{
  "pages": ["index", "getting-started"]
}

{
  "pages": [
    "components",
    "---My Separator---",
    "...folder",
    "...",
    "!file",
    "!otherFolder",
    "[Vercel](https://vercel.com)",
    "[Triangle][Vercel](https://vercel.com)"
  ]
}

資料夾索引複製錨點連結

當資料夾擁有索引項目時，該資料夾即可點擊，點擊後會跳轉至索引項目。

預設情況下，索引項目是各資料夾中的 index 檔案。您也可以自行指定資料夾的索引項目，支援 路徑 與 連結 兩種類型。

{
  // 假設該資料夾下有 "overview.mdx" 檔案
  "pagesIndex": "overview"
}

圖示複製錨點連結

由於 Fumadocs 並未內建圖示函式庫，您必須在執行階段將圖示名稱轉換為 JSX 元素，再以元件的形式算繪。

您可以為 loader() 加入 icon 處理器。

i18n 路由複製錨點連結

您可以為 i18n 路由定義不同的風格。

import type { I18nConfig } from 'fumadocs-core/i18n';

export const i18n: I18nConfig = {
  // 預設值
  parser: 'dot',
  // 或
  parser: 'dir',
};

路徑參數複製錨點連結

系統會依參數的每個值，各產生一個名為 [name] 的資料夾。請在該資料夾的 meta 檔案中，於 staticParams 列出這些值：

{
  "title": "Framework",
  "staticParams": [{ "framework": "waku" }, { "framework": "astro" }]
}

meta 檔案會套用到每個產生的資料夾。頁面會以 props 的形式接收其參數，也可以透過 loader() 回傳的 page.params 取得。

在 meta.ts 中，您也可以改為匯出一個以參數為輸入的函式，並將 staticParams 作為具名匯出：

const names = { waku: 'Waku', astro: 'Astro' };

export const staticParams = [{ framework: 'waku' }, { framework: 'astro' }];

export default ({ framework }: { framework: keyof typeof names }) => ({
  title: names[framework],
});

頁面參數複製錨點連結

頁面也可以在 frontmatter 中列出 staticParams。若所屬資料夾也有列出，則只會針對兩者共有的值產生該頁面。

---
title: Fumadocs MDX
staticParams:
  - framework: waku
---

靜態路徑複製錨點連結

位於固定路徑的檔案，優先順序高於動態產生的檔案。例如，astro/deploy.mdx 會取代 [framework]/deploy.mdx 所產生的 astro 頁面。meta 檔案也適用相同規則。

在地化頁面複製錨點連結

啟用 i18n 時，語系本身的檔案會優先於其備用語系的檔案。以 /cn/docs/astro/deploy 為例，會依序採用第一個存在的檔案：

1. astro/deploy.cn.mdx
2. [framework]/deploy.cn.mdx
3. astro/deploy.mdx
4. [framework]/deploy.mdx

在地化頁面會優先從 meta.cn.json 讀取 staticParams。使用 dir 解析器時，每個語言資料夾會各自列出其值。