文件系統

Saavo 已串接好文件系統所需的頁面、導覽與內容處理流程。使用手冊、開發指南與說明內容，都能直接撰寫於 content/docs，不必另外建立 CMS，也不需要再整合其他文件框架。

目前文件系統包含側邊欄、行動版導覽、導覽路徑、文章目錄、上一篇與下一篇、全文搜尋、圖片點擊放大、文章中繼資料與 SEO 資訊。每篇文章也提供 Markdown 原文、複製 Markdown，以及在 ChatGPT、Claude、Cursor 與 Scira AI 中開啟的入口。

開關與目錄

設定位於 config/deploy.ts：

content: {
    docs: {
        enabled: true,
        baseUrl: '/docs',
        contentDir: '/content/docs',
    },
}

預設語言不加上語言前綴，例如 /docs。其他語言使用 /{語言代碼}/docs，例如 /zh-Hant/docs。將 enabled 改為 false 後，就不會註冊文件路由，需要重新啟動開發伺服器或重新建置才會生效。

檔案如何變成頁面

文件依語言分成不同目錄，每個目錄都可以有自己的首頁、內文與側邊欄設定。以下以繁體中文的「快速開始」為例：

content/docs/zh-Hant/
├── 000_index.mdx
├── meta.json
└── 002_quick-start/
    ├── 000_index.mdx
    ├── 001_create-project.mdx
    ├── 002_local-development.mdx
    ├── 003_first-deployment.mdx
    └── meta.json

對應的公開位址如下：

檔案與目錄名稱前面的 000_、001_ 只用於排序，產生 URL 時會移除。目前規則只辨識「三位數字加底線」。例如，001_foo 會產生 foo，但 01_foo、2026_roadmap 不會移除數字前綴。

組織側邊欄

根目錄的 meta.json 決定第一層章節與分隔線，子目錄的 meta.json 則決定該章節的標題、圖示、首頁與內文順序。

{
    "title": "快速開始",
    "icon": "Rocket",
    "pages": [
        "001_create-project",
        "002_local-development",
        "003_first-deployment"
    ],
    "pagesIndex": "000_index"
}

pagesIndex 將 000_index.mdx 設為目錄首頁，按下側邊欄的章節名稱就會開啟該頁。pages 只列出內文頁面，不要再重複放入同一個首頁。

根目錄也可以使用 ---名稱--- 新增群組標題，使用 ...目錄名稱 展開另一個目錄的頁面。修改後，請先查看桌面版與行動版側邊欄，確認順序、摺疊狀態與連結都正常。

撰寫文章

最少只需要 title 與 description：

---
title: "串接付款"
description: "設定付款 Provider、方案與正式環境回呼。"
---

從這裡開始撰寫內文。

也可以依需要填寫：

draft 不會加入搜尋索引，但知道位址的人仍可能直接開啟頁面。不能公開的內容，請不要部署到正式環境，也不要只依賴 status 隱藏。

內文支援一般 Markdown、GFM 表格與工作清單，也能使用已註冊的 MDX 元件：

• Callout
• Steps、Step
• Tabs、Tab
• Accordions、Accordion
• Files、Folder、File
• TypeTable

Markdown 圖片會自動支援點擊放大。如果圖片放在 public 中，內文請使用網站根路徑，例如：

![文件搜尋](/docs/features/docs_page.webp)

不要直接在 MDX 使用業務頁面的私有 React 元件。如果要新增共用元件，請先在 src/libs/documentation/mdx.tsx 註冊，再於文章中引用。

如何撰寫內部連結

每個語言目錄都是自包含的。連到其他文章時，使用目前語言從網站根目錄開始的路徑，例如繁體中文的 /zh-Hant/docs/prepare、簡體中文的 /zh-Hans/docs/prepare 與英文的 /docs/prepare。預設語言英語沒有語言前綴，同一語言的文件不應跳轉到其他語言的文章作為替代。

無論目前位於快速開始的目錄首頁，或該目錄下的某篇內文，繁體中文連結都可以寫成：

[事前準備](/zh-Hant/docs/prepare)
[建立專案](/zh-Hant/docs/quick-start/create-project)

瀏覽器依目前頁面的公開 URL 解析相對連結，不會依 MDX 檔案在磁碟上的位置計算。頁面位址也沒有結尾的斜線。例如，從 /zh-Hant/docs/quick-start 前往 /zh-Hant/docs/prepare，相對連結是 ./prepare，從 /zh-Hant/docs/quick-start/create-project 前往同一目標，則是 ../prepare。使用完整的站內路徑可以避免這種差異。

各語言的對應標題統一使用明確的英文錨點。標題文字可以翻譯，錨點 ID 保持一致，例如：

## 串接付款 [#integrate-payments]

[本節](#integrate-payments)

連到另一篇文章的某一節時，將該文章的目前語言路徑與英文錨點組合起來。每篇文章內的 ID 不可重複，修改 ID 時需要同步更新文件中所有參照它的連結。

公共圖片屬於共用資源，繼續使用 /docs/...webp 這類圖片路徑。外部參考資料使用其實際的 https:// 位址。應用程式碼連到文件時，應依目前語言與專案設定產生最終公開位址。

本機預覽與搜尋

執行：

npm run dev

predev 會先產生 Content Collections 與各語言的靜態搜尋索引，再啟動 Vite。平常修改內文時，開發環境會更新頁面，但刻意不會自動更新搜尋索引。

新增目錄、調整設定，或發現內容未更新時，可以手動執行下列指令：

npm run gen:collections
npm run gen:search-index

搜尋索引會依語言與內容類型分別產生，檔名包含內容雜湊。發布前除了檢查文章頁面，也要搜尋新標題與內文關鍵字，確認目前語言可以找到該文章。

每篇文件也提供對應的 .md 位址，例如：

/zh-Hant/docs/quick-start/create-project.md

頁面上的「複製 Markdown」與 AI 工具入口，都使用這份原文。內文出現問題時，應先修正 MDX 來源檔案，不要修改產生後的 HTML 或 .md 回應。

發布到正式環境

開發環境直接讀取 Content Collections，正式環境則從 MAIN_KV 讀取序列化後的文章。發布時，需要同時更新文章資料，以及建置產生的靜態搜尋索引。

一般專案更新請使用 npm run deploy:update。目前範本的部署流程會完成建置、應用程式部署與 kv:sync:remote 內容同步，首次部署的 deploy:init 也包含內容同步步驟。

如果需要個別同步內容，可以使用：

• npm run kv:sync:local：產生 Content Collections，並同步到本機 KV。
• npm run kv:sync:remote：產生 Content Collections，並同步到遠端 MAIN_KV。

執行遠端同步前，請確認 Wrangler 使用正確的帳戶與目標資源。單獨同步 KV，不會發布新的靜態搜尋索引，因此內文變更後，仍需重新建置並部署應用程式。發布完成後，請檢查文章、搜尋、側邊欄與 .md 位址。

上線前檢查

• 文件開關與 baseUrl 符合產品的實際情況。
• 每個啟用的語言都有對應目錄與必要頁面。
• meta.json 使用實際檔名，側邊欄沒有缺少頁面或重複首頁。
• 公開 URL 中沒有出現排序前綴。
• 已逐一按下目錄首頁中的跨模組連結，確認導向正確。
• 標題可以產生正常的文章目錄，按下錨點後也能正確定位。
• 圖片可以顯示，也能按一下放大。
• 可以透過目前語言的搜尋找到新文章。
• Markdown 原文位址與複製功能正常。
• 已重新產生並上傳 MAIN_KV 內容。
• 已替換範本文案、範例產品與占位圖片。

常見問題

接下來

• 新增文件語言 → 新增語言
• 發布部落格文章 → 部落格
• 查看實際產品的網站與品牌設定 → WebpageToPDF 實作教學

文件系統的程式碼已準備好，真正需要長期維護的是內容、連結與發布流程。每次調整目錄後，先檢查側邊欄與連結，再更新搜尋索引及正式環境 KV。