文件站維護
本文件站基於 VitePress 建置,原始碼位於儲存庫的 docs/ 資料夾,並透過 GitHub Actions 自動部署到 GitHub Pages。
資料夾結構
docs/
├── .vitepress/
│ ├── config.mts 站台設定(三語 locales:導覽、側邊欄、佈景主題)
│ └── theme/ 自訂佈景主題(元件文案隨 useData().lang 切換)
├── public/ 靜態資源(圖片/圖示,按根路徑引用;三語共用)
├── index.md 簡體中文首頁(hero + features)
├── guide/ 簡體中文使用說明(面向使用者)
├── dev/ 簡體中文開發文件(面向開發者)
├── changelog/ 更新日誌(由 GitHub Releases 動態產生)
├── en/ 英文,結構與根目錄一致
│ ├── index.md
│ ├── guide/
│ ├── dev/
│ └── changelog/
└── zh-tw/ 繁體中文,結構與根目錄一致
├── index.md
├── guide/
├── dev/
└── changelog/兩類文件分別放在 guide/ 與 dev/ 兩個主資料夾下,並在 config.mts 中設定了各自的頂部導覽入口與獨立側邊欄。
多語言
站台用 VitePress 的 locales 提供三種語言:
| 語言 | 路徑前綴 | 資料夾 |
|---|---|---|
| 简体中文 | /(root) | docs/ |
| English | /en/ | docs/en/ |
| 繁體中文 | /zh-tw/ | docs/zh-tw/ |
- 簡體中文是內容基準,且留在根路徑,因此既有外部連結與 SEO 不受影響。新增或修改文件時先寫簡體中文,再同步另外兩種語言。
- 每種語言在
config.mts的locales下有自己的nav、sidebar、editLink、footer;側邊欄連結必須帶各自的路徑前綴(如/en/guide/binding)。 - 文件內的站內連結要指向同語言頁面,否則讀者會被跳出目前語言。
.vitepress/theme/下的自訂元件(StatusBar.vue、ReleaseMeta.vue)透過useData().lang取目前語言切換文案,三語共用同一份元件。
更新日誌內容不翻譯
changelog/ 的版本頁由 [version].paths.ts 從 GitHub Releases 動態產生,內文即 Release body(以簡體中文撰寫),三種語言下都按原文顯示;僅頁面外殼(標題、「下載」、發布時間等)隨語言切換。
本機預覽
文件相關的指令碼在根 package.json 中:
bash
# 安裝相依套件(使用 pnpm;也可用 npm)
pnpm install
# 本機開發預覽(熱重新載入)
pnpm docs:dev
# 生產建置
pnpm docs:build
# 預覽生產建置產物
pnpm docs:preview建置產物已忽略
docs/.vitepress/dist 與 docs/.vitepress/cache 已在 .gitignore 中忽略,不要提交。
圖片與螢幕擷取畫面
- 將圖片放入
docs/public/,在 Markdown 中以根路徑引用,例如。 - 站台部署在自訂網域下,
base為/。若改為 GitHub Pages 專案站台(/ZoneDeck/),VitePress 會自動為public資源補上前綴,Markdown 裡始終不需手寫base。
VitePress 特性
文件中廣泛使用了 VitePress 的容器提示框,撰寫時請保持一致:
md
::: tip 提示
用於補充建議、最佳做法。
:::
::: warning 注意
用於提醒潛在風險/易錯點。
:::
::: danger 危險
用於強調破壞性操作。
:::
::: info 資訊
中性的補充說明。
:::
::: details 展開檢視
預設摺疊的次要內容。
:::部署工作流程
文件透過 .github/workflows/deploy-docs.yml 自動部署到 GitHub Pages:
- 自動觸發:改動涉及
docs/**或工作流程本身。 - 手動觸發:在 GitHub Actions 頁面透過
workflow_dispatch手動執行。
工作流程執行 pnpm install → pnpm docs:build → 上傳並部署到 Pages。