入門
線上試用
您可以在 StackBlitz 上直接在瀏覽器中試用 VitePress。
安裝
先決條件
- Node.js 版本 18 或更高。
- 透過命令列介面 (CLI) 存取 VitePress 的終端機。
- 支援 Markdown 語法的文字編輯器。
- 建議使用 VSCode，以及 官方 Vue 擴充功能。
VitePress 可以單獨使用，或安裝到現有的專案中。在兩種情況下，您都可以使用以下方式安裝
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ bun add -D vitepress出現遺失的對等相依性警告嗎？
如果使用 PNPM，您會注意到 @docsearch/js 有遺失的對等相依性警告。這不會阻止 VitePress 運作。如果您想隱藏此警告，請將以下內容新增到您的 package.json
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}注意
VitePress 是僅限 ESM 的套件。請勿使用 require() 匯入它，並確保您最近的 package.json 包含 "type": "module"，或將相關檔案的副檔名從 .vitepress/config.js 變更為 .mjs/.mts。請參閱 Vite 的疑難排解指南 以取得更多詳細資訊。此外，在非同步 CJS 背景中，您可以改用 await import('vitepress')。
設定精靈
VitePress 附帶一個命令列設定精靈，可協助你建立基本專案架構。安裝後，執行以下指令啟動精靈
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress init系統會詢問你幾個簡單的問題
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└Vue 作為對等相依性
如果你打算執行使用 Vue 元件或 API 的自訂，也應該明確將 vue 安裝為相依性。
檔案結構
如果你正在建立一個獨立的 VitePress 網站，可以在目前的目錄 (./) 中建立網站架構。不過，如果你將 VitePress 安裝在現有的專案中，並與其他原始碼並存，建議在巢狀目錄 (例如 ./docs) 中建立網站架構，以將其與專案的其他部分分開。
假設你選擇在 ./docs 中建立 VitePress 專案架構，產生的檔案結構應如下所示
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsondocs 目錄被視為 VitePress 網站的專案根目錄。.vitepress 目錄是 VitePress 設定檔、開發伺服器快取、建置輸出和選用主題自訂程式碼的保留位置。
提示
預設情況下，VitePress 會將其開發伺服器快取儲存在 .vitepress/cache 中，並將生產建置輸出儲存在 .vitepress/dist 中。如果你使用 Git，應該將它們新增到 .gitignore 檔案中。這些位置也可以設定。
設定檔
設定檔 (.vitepress/config.js) 允許你自訂 VitePress 網站的各個方面，最基本的選項是網站的標題和說明
// .vitepress/config.js
export default {
// site-level options
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// theme-level options
}
}你也可以透過 themeConfig 選項設定主題的行為。請參閱設定參考，以取得所有設定選項的完整詳細資料。
原始檔
.vitepress 目錄外的 Markdown 檔案被視為原始檔。
VitePress 使用基於檔案的路由：每個 .md 檔案會編譯成對應的 .html 檔案，路徑相同。例如，index.md 會編譯成 index.html，並可以在 VitePress 網站的根路徑 / 中瀏覽。
VitePress 也提供產生乾淨 URL、重寫路徑和動態產生頁面的功能。這些功能會在 路由指南 中說明。
開始執行
如果你在設定過程中允許，此工具也應該會將下列 npm 指令注入到你的 package.json 中
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}docs:dev 指令會啟動一個具有即時熱更新功能的本機開發伺服器。使用下列指令執行
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:dev除了 npm 指令之外，你也可以使用下列指令直接呼叫 VitePress
$ npx vitepress dev docs$ pnpm vitepress dev docs$ yarn vitepress dev docs$ bun vitepress dev docs更多指令列用法說明請參閱 CLI 參考。
開發伺服器應該會在 https://127.0.0.1:5173 執行。在瀏覽器中瀏覽 URL，即可看到你的新網站實際運作的樣子！