[TOC] > 編寫本文時（2022.9）使用的版本： VitePress ^1.0.0-alpha.17，目前（2023.12）最新版 ^1.0.0-rc.31。相比之前有些變化，本文部分內(nèi)容已過時 #### 1. VitePress 介紹 --- VitePress 還未正式發(fā)布，當前 (2022-09-20) 處于內(nèi)測階段，本文為初次使用總結(jié)，正式發(fā)布后用法可能略有變化 **VitePress 是什么 ？** [VitePress](https://vitepress.dev) 是 [VuePress](https://vuepress.vuejs.org) 的小兄弟， VitePress 構(gòu)建在 Vite 之上，而 VuePress 構(gòu)建在 Webpack 上，也就是它們使用的打包工具不同，并且 VitePress 解決了 VuePress 設(shè)計上的一些缺陷 **已經(jīng)有了 VuePress，為什么又開發(fā)了一個 VitePress ？** 關(guān)于開發(fā) VitePress 的動機，在官網(wǎng)上已經(jīng)做了詳細介紹: <https://vitepress.dev/guide/what-is-vitepress> 因為 VuePress 構(gòu)建在 Webpack 之上，即使只修改了一個文件，也要重新編譯整個項目才能正常顯示新的內(nèi)容，當項目頁面比較多時，這樣會很慢。Vite 很好地解決了這些問題，僅編譯需要編譯的頁面。 除此之外，它還使用 Vue3，更輕的頁面重量，更快的開發(fā)服務(wù)器啟動，更快的熱更新 #### 2. VitePress 入門 --- **初始化項目** ``` # 創(chuàng)建并進入一個目錄 mkdir website && cd website # 初始化項目 yarn init -y ``` **安裝 VitePress** ``` # 將 vitepress 和 vue 安裝為開發(fā)時依賴 yarn add vitepress vue --dev # 創(chuàng)建第一個文檔 mkdir docs && echo '# Hello VitePress' > docs/index.md ``` ** 添加運行腳本** ```json { "scripts": { "dev": "vitepress dev docs", "build": "vitepress build docs", "serve": "vitepress serve docs" } } ``` **啟動開發(fā)環(huán)境，在本地服務(wù)器中提供文檔站點。VitePress 將啟動一個本地站點 `http://localhost:5173`** ``` yarn dev ``` **添加更多頁面** 直接訪問 `http://localhost:5173` 默認顯示 `index.md`，現(xiàn)在添加了兩個 md 文件，如下所示: 訪問地址分別為 `http://localhost:5173/back/php.html`、`http://localhost:5173/liang.html` 這就是 VitePress 的基本工作方式，目錄結(jié)構(gòu)與 URL 路徑相對應(yīng) ``` $ tree docs docs ├── index.md ├── back │   └── php.md └── liang.md ``` #### 3. VitePress 配置 --- 目前為止，已經(jīng)有一個最基本的 VitePress 文檔站點，接下來可以通過增加配置去完善它。比如: 頂部導(dǎo)航，側(cè)邊欄菜單等 VitePress 配置文件位置: ``` docs/.vitepress/config.js ``` VitePress 配置文件導(dǎo)出一個 JS 對象，下面是最簡單的配置，title 為站點標題，description 為網(wǎng)站描述 ```javascript export default { title: 'VitePress', description: 'Just playing around.' } ``` 項目打包后生成的 index.html 文件頭部: Hello VitePress 是頁面大標題，VitePress 是站點標題 ``` <title>Hello VitePress | VitePress</title> <meta name="description" content="Just playing around."> ``` #### 4. VitePress 導(dǎo)航 --- 導(dǎo)航欄 (Nav) 是頁面頂部區(qū)域，包含站點標題、導(dǎo)航欄鏈接 **導(dǎo)航鏈接** VitePress 導(dǎo)航鏈接所有類型配置如下所示: ```javascript export default { themeConfig: { nav: [ // 顯示 docs/guide.md 內(nèi)容 { text: "Guide", link: "/guide" }, // 跳轉(zhuǎn)到外部URL鏈接 { text: "Blog", link: "http://m.cfacat.cn" }, // 下拉菜單 { text: "Dropdown Menu", items: [ { text: "Item A", link: "..." }, { text: "Item B", link: "..." }, ], }, // 下拉菜單分組-包含標題 { text: "Dropdown Group", items: [ { // 分組標題 text: "前端", items: [ { text: "Vue", link: "..." }, { text: "React", link: "..." }, ], }, { // 分組標題 text: "后端", items: [ { text: "PHP", link: "..." }, { text: "Java", link: "..." }, ], }, ], }, // 下拉菜單分組-省略標題 { text: "Dropdown Group", items: [ { items: [ { text: "Vue", link: "..." }, { text: "React", link: "..." }, ], }, { items: [ { text: "PHP", link: "..." }, { text: "Java", link: "..." }, ], }, ], }, ], }, } ``` **自定義導(dǎo)航鏈接的活動狀態(tài) (高亮顯示)** 默認情況下，處于當前路徑時，導(dǎo)航菜單高亮顯示。 如果想要自定義匹配路徑高亮顯示，可以使用 `activeMatch` 定義正則表達式字符串去匹配路徑 ```javascript export default { themeConfig: { nav: [ { text: "Guide", link: "/guide" }, { text: "Dropdown Group", // 當前路徑下導(dǎo)航鏈接高亮顯示 activeMatch: "^/lang/", items: [ { text: "前端", items: [ { text: "Vue", link: "/lang/vue" }, { text: "React", link: "/lang/react" }, ], }, ], }, ], }, } ``` #### 5. VitePress 側(cè)邊欄 --- 側(cè)邊欄是文檔的主要導(dǎo)航塊，在配置文件中通過 `themeConfig.sidebar` 配置側(cè)邊欄 **單個側(cè)邊欄** ```javascript export default { themeConfig: { sidebar: [ { text: "Guide", items: [ { text: "Intro", link: "..." }, { text: "Started", link: "..." }, ], }, { text: "Lang", items: [ { text: "Vue", link: "..." }, { text: "React", link: "..." }, ], }, ], } } ``` **可折疊的側(cè)邊欄組** 給側(cè)邊欄組添加一個 `collapsible: true`，則會顯示一個按鈕可以切換折疊和展開該側(cè)邊欄組 側(cè)邊欄組默認是展開的，當給側(cè)邊欄組添加一個 `collapsed: true`，該側(cè)邊欄組則會默認折疊 ```javascript export default { themeConfig: { sidebar: [ { text: "Lang", collapsible: true, collapsed: true, items: [...], }, ], } } ``` **多個側(cè)邊欄** 很多情況下需要根據(jù)文檔內(nèi)容顯示不同的側(cè)邊欄，比如根據(jù)導(dǎo)航菜單顯示不同的側(cè)邊欄 ``` ├─ guide/ │ ├─ intro.md │ ├─ theme.md └─ config/ ├─ app.md └─ frontmatter.md ``` ```javascript export default { themeConfig: { sidebar: { "/guide": [ { text: "Guide", items: [ { text: "Intro", link: "/guide/Intro" }, { text: "Theme", link: "/guide/Theme" }, ], }, ], "/config": [ { text: "Config", items: [ { text: "App", link: "/config/app" }, { text: "Frontmatter", link: "/config/frontmatter" }, ], }, ], }, } } ```