[TOC] > 编写本文时（2022.9）使用的版本： VitePress ^1.0.0-alpha.17，目前（2023.12）最新版 ^1.0.0-rc.31。相比之前有些变化，本文部分内容已过时 #### 1. VitePress 介绍 --- VitePress 还未正式发布，当前 (2022-09-20) 处于内测阶段，本文为初次使用总结，正式发布后用法可能略有变化 **VitePress 是什么 ？** [VitePress](https://vitepress.dev) 是 [VuePress](https://vuepress.vuejs.org) 的小兄弟， VitePress 构建在 Vite 之上，而 VuePress 构建在 Webpack 上，也就是它们使用的打包工具不同，并且 VitePress 解决了 VuePress 设计上的一些缺陷 **已经有了 VuePress，为什么又开发了一个 VitePress ？** 关于开发 VitePress 的动机，在官网上已经做了详细介绍: <https://vitepress.dev/guide/what-is-vitepress> 因为 VuePress 构建在 Webpack 之上，即使只修改了一个文件，也要重新编译整个项目才能正常显示新的内容，当项目页面比较多时，这样会很慢。Vite 很好地解决了这些问题，仅编译需要编译的页面。 除此之外，它还使用 Vue3，更轻的页面重量，更快的开发服务器启动，更快的热更新 #### 2. VitePress 入门 --- **初始化项目** ``` # 创建并进入一个目录 mkdir website && cd website # 初始化项目 yarn init -y ``` **安装 VitePress** ``` # 将 vitepress 和 vue 安装为开发时依赖 yarn add vitepress vue --dev # 创建第一个文档 mkdir docs && echo '# Hello VitePress' > docs/index.md ``` ** 添加运行脚本** ```json { "scripts": { "dev": "vitepress dev docs", "build": "vitepress build docs", "serve": "vitepress serve docs" } } ``` **启动开发环境，在本地服务器中提供文档站点。VitePress 将启动一个本地站点 `http://localhost:5173`** ``` yarn dev ``` **添加更多页面** 直接访问 `http://localhost:5173` 默认显示 `index.md`，现在添加了两个 md 文件，如下所示: 访问地址分别为 `http://localhost:5173/back/php.html`、`http://localhost:5173/liang.html` 这就是 VitePress 的基本工作方式，目录结构与 URL 路径相对应 ``` $ tree docs docs ├── index.md ├── back │   └── php.md └── liang.md ``` #### 3. VitePress 配置 --- 目前为止，已经有一个最基本的 VitePress 文档站点，接下来可以通过增加配置去完善它。比如: 顶部导航，侧边栏菜单等 VitePress 配置文件位置: ``` docs/.vitepress/config.js ``` VitePress 配置文件导出一个 JS 对象，下面是最简单的配置，title 为站点标题，description 为网站描述 ```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 导航 --- 导航栏 (Nav) 是页面顶部区域，包含站点标题、导航栏链接 **导航链接** VitePress 导航链接所有类型配置如下所示: ```javascript export default { themeConfig: { nav: [ // 显示 docs/guide.md 内容 { text: "Guide", link: "/guide" }, // 跳转到外部URL链接 { text: "Blog", link: "https://www.itqaq.com" }, // 下拉菜单 { 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: "..." }, ], }, ], }, ], }, } ``` **自定义导航链接的活动状态 (高亮显示)** 默认情况下，处于当前路径时，导航菜单高亮显示。 如果想要自定义匹配路径高亮显示，可以使用 `activeMatch` 定义正则表达式字符串去匹配路径 ```javascript export default { themeConfig: { nav: [ { text: "Guide", link: "/guide" }, { text: "Dropdown Group", // 当前路径下导航链接高亮显示 activeMatch: "^/lang/", items: [ { text: "前端", items: [ { text: "Vue", link: "/lang/vue" }, { text: "React", link: "/lang/react" }, ], }, ], }, ], }, } ``` #### 5. VitePress 侧边栏 --- 侧边栏是文档的主要导航块，在配置文件中通过 `themeConfig.sidebar` 配置侧边栏 **单个侧边栏** ```javascript export default { themeConfig: { sidebar: [ { text: "Guide", items: [ { text: "Intro", link: "..." }, { text: "Started", link: "..." }, ], }, { text: "Lang", items: [ { text: "Vue", link: "..." }, { text: "React", link: "..." }, ], }, ], } } ``` **可折叠的侧边栏组** 给侧边栏组添加一个 `collapsible: true`，则会显示一个按钮可以切换折叠和展开该侧边栏组 侧边栏组默认是展开的，当给侧边栏组添加一个 `collapsed: true`，该侧边栏组则会默认折叠 ```javascript export default { themeConfig: { sidebar: [ { text: "Lang", collapsible: true, collapsed: true, items: [...], }, ], } } ``` **多个侧边栏** 很多情况下需要根据文档内容显示不同的侧边栏，比如根据导航菜单显示不同的侧边栏 ``` ├─ 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" }, ], }, ], }, } } ```