Skip to content

建立 2026-09-15 更新 2026-09-15

檔案即路由

VitePress 用檔案路徑決定網址，不必維護一份路由表。新增一頁就是新增一個 .md。

路徑怎麼對應

假設原始檔在 docs/：

docs/
├─ index.md              → /
├─ guide/
│  ├─ index.md           → /guide/  （或 /guide/index.html）
│  └─ getting-started.md → /guide/getting-started
└─ api.md                → /api

index.md 代表該資料夾的入口。頂欄、側欄裡的 link 要跟這些路徑一致，少一個斜線或拼錯檔名，點下去就是 404。

寫連結時的習慣

在 guide/getting-started.md 裡：

[回指南首頁](./)
[上一頁](./index.md)
[API](../api)

相對路徑較不容易在搬資料夾時寫死。跨分類也可以用從站根開始的絕對路徑：/guide/getting-started。

預設產生的頁面帶 .html 後綴。若想讓網址看起來像 /guide/getting-started（沒有 .html），在 config 設 cleanUrls: true，並確認主機（例如 Nginx、GitHub Pages）知道要把該路徑指到對應 HTML。設定錯誤時重新整理內頁會 404。

進階：改寫與動態路由

多數文件站用不到。需要時再查官方〈路由〉：

  • rewrites：讓「檔案放很深、網址卻很短」，例如把 packages/pkg-a/src/index.md 對外顯示成 /pkg-a/。
  • 動態路由：packages/[pkg].md 搭配 [pkg].paths.js，在建置當下展開成多頁。因為是 SSG，所有可能的路徑必須在 build 時就決定，不能等使用者請求才算。

先把資料夾結構整理到「看資料夾就知道網址」，通常比上這兩項更有用。