專案結構
向導若把站點放在 ./docs，目錄會長得像這樣：
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js # 或 config.ts / config.mts
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
兩個位置不要搞混：
| 名稱 | 是什麼 | 放什麼 |
|---|---|---|
| 專案根目錄（project root） | 含有 .vitepress/ 的那一層 |
設定檔、快取、建置輸出、自訂主題 |
| 原始檔目錄（source） | Markdown 所在目錄，預設等於專案根目錄 | 你寫的 .md、public/ 靜態檔 |
指令 vitepress dev docs 的 docs 就是告訴 CLI：「專案根目錄在 ./docs」。所以設定檔是 docs/.vitepress/config.js，不是 repo 最外層。
.vitepress/ 裡有什麼
- config：站名、
base、Markdown 選項、themeConfig（頂欄、側欄、搜尋）。 - cache：開發伺服器快取，應加入
.gitignore。 - dist：
build產出，預設也在這裡，同樣不要提交。 - theme/（可選）：要擴充或自訂主題時才需要。
.vitepress/ 外面的 .md 才是頁面來源。index.md 會變成網站首頁。
獨立站還是嵌在專案裡
- 只有文件、沒有產品程式碼：可以把 VitePress 直接初始化在 repo 根目錄（
./）。 - 文件跟套件／應用放在同一個 repo：請初始化在
./docs，避免 Markdown 與src/混在一起。
靜態資源（不會經過打包的圖片、robots.txt、平台用的 _headers）放在原始檔目錄的 public/，建置時會原樣複製到輸出根目錄。詳見官方〈資源處理〉。