--- theme: scrolls-light highlight: atelier-lakeside-dark --- > `VitePress` 是基于 `Vite` 的静态网站生成器（文档工具）。 ## 初始化项目 1. 创建文件夹并进入到项目的目录中。当然如果你喜欢可以完全手动操作。 ```bash # mkdir 创建文件夹指令； && 表示当前命令执行成功后会执行下一条指令。 mkdir vitepress-starter && cd vitepress-starter ``` 2. 初始化项目，官网默认使用了 `yarn` 作为依赖管理工具。 ```bash yarn init ``` 3. 安装项目所需的依赖 `vitepress` 和 `vue` ```bash yarn add --dev vitepress vue ``` 4. 创建第一个示例文件。如果你愿意可以手动操作 ```bash # echo 写入内容到项目的 docs/index.md 中 mkdir docs && echo '# Hello VitePress' > docs/index.md ``` 5. 在 `package.json` 中增加打包以及运行的指令。 ```js "scripts": { "docs:dev": "vitepress dev docs", // 本地运行调试 "docs:build": "vitepress build docs", // 项目打包：最终结果会在 .vitepress/dist 中 "docs:serve": "vitepress serve docs" // 预览打包后的效果，此命令只有 build 成功后才会执行成功。 }, ``` 6. 执行 `npm run docs:dev` 看到如下界面即表示运行成功。 ![vitepress01.jpg](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/85a0872c87854e85bc9c99c206571ca3~tplv-k3u1fbpfcp-watermark.image?) ## 项目配置目标 `1:1` 复现 `vitepress` 的布局。 ### 布局 `VitePress` 的布局整体可以分为 4 种，分别为：`doc` `page` `home` 和没有任何默认布局（空白页面） ``` 需要注意的是，下面的语法一定要写在 md 文档的头部才会生效 --- layout: doc | page | home --- ``` ```js // 通过此语法可以将整个页面变成空白页面，适合自定义的布局 {{ $formatter.layout }} ``` ### 首页配置、`Home` 布局

点击查看首页配置，并结合下图参考对应配置

``` --- layout: home hero: name: 主标题 text: 内容信息 tagline: 副内容信息 image: src: /logo.png alt: 网站的 logo 图片 actions: - theme: brand text: 快速开始 link: /guide/what-is-vitepress - theme: alt text: 在 github 上查看 link: https://github.com/vuejs/vitepress features: - icon: ⚡️ title: 这里是功能区 1 details: 这里是功能区 1 详情信息 - icon: 🖖 title: 这里是功能区 2 details: 这里是功能区 2 详情信息 - icon: 🛠️ title: 这里是功能区 3 details: 这里是功能区 3 详情信息 --- ```

![vitepress02.jpg](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f5ea565d64404286b1cb756dbe600f10~tplv-k3u1fbpfcp-watermark.image?) ### `Page` `Doc` 布局这两种基本都是在书写文档的详细内容时而需要的布局。从表现形式上看也只是文章内容显示位置上面的不同及 `page` 相比较 `doc` 会默认缺少一些内容比如 `Edit Link`，`NextPage` `PrePage` 等。大多数情况下在编写内容时推荐使用 `doc`。 ``` --- layout: doc --- ``` ![vitepress05.jpg](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f529c86c6eb44567a965bef39db86ecc~tplv-k3u1fbpfcp-watermark.image?) ``` --- layout: page --- ``` ![vitepress06.jpg](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2c4cf259446146d7a48e31a2059f3f56~tplv-k3u1fbpfcp-watermark.image?) ### 如何创建文档假设你现在点击页面上的 **快速开始** 不出意外直接 404 了，此时查看首页配置 **快速开始的 `link` 为 `/guide/what-is-vitepress`** 解决此问题：在 `/docs` 下新建文件 `guide/what-is-vitepress.md` 随便写入内容。再次点击即可访问。 `VitePress` 会根据 `docs/` 下的文件内容映射成可访问路由。比如 `/docs/guide/getting-started.md` 则访问地址为 `http://localhost:5173/guide/getting-started` 文档书写规范推荐为以下结构 ``` ├─ docs │ ├─ guide │ │ ├─ getting-started.md │ │ └─ what-is-vitepress.md │ ├─ theme │ │ ├─ theme-nav.md │ │ └─ theme-sidebar.md │ └─ index.md └─ package.json ``` ## 全局配置对象 `VitePress` 提供了一个配置对象，该对象应当存在于 `/docs/.vitepress/config.js` 中。在这里可以配置 `Nav` `Sidebar` 等重要信息。在 `.vitepress` 中新建 `config.js` 文件并增加如下代码。 ```js import { defineConfig } from 'vitepress'; export default defineConfig({}); ``` ### `Nav` 导航栏 `Nav` 配置有两种方式，直接点击跳转和下拉菜单样式。详情参考以下配置信息。主要有以下字段： - `link`：当触发点击事件时跳转的地址；可以是外链也可以是项目内的路径。 - `activeMatch`：需要被高亮的 `nav` 。 - `text`：显示到页面的信息。 ```js import { defineConfig } from 'vitepress'; export default defineConfig({ themeConfig: { nav: [ { text: 'Guide', link: '/guide', activeMatch: '/guide/what-is-vitepress' }, { text: '下拉选择框', items: [ { text: 'options-1', link: '/' }, { text: 'options-2', link: 'http://www.baidu.com' } ] } ] } }); ``` **社交链接** 严格来说不算 `nav` 范畴，但是显示位置基本相同。 ```js export default defineConfig({ themeConfig: { socialLinks: [{ icon: "github", link: "https://github.com" }], } }); ``` - `icon`：`discord` `facebook` `github` `instagram` `linkedin` `slack` `twitter` `youtube` 或者 `svg` 字符串 - `link`：跳转链接。对标如下页面： ![vitepress03.jpg](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/50b331adbcdf46df9d5b10acbd94bd07~tplv-k3u1fbpfcp-watermark.image?) ### `Sidebar` 侧边栏导航 `sidebar` 同样有两种配置方式。接受以下配置对象： - `text`：侧边栏块的 `title`。 - `items`：侧边栏的每一项，`text` 为标题；`link` 为跳转地址。 - `collapsible`：菜单是否为可折叠的 `Boolean`。 - `collapsed`：是否默认折叠 `Boolean` 只有配置 `collapsiable` 时此配置才会生效。数组配置方式 ```js sidebar: [ { text: 'Guide', items: [ { text: 'Introduction', link: '/guide/what-is-vitepress' }, { text: 'Getting Started', link: '/getting-started' }, ], collapsible: true, collapsed: true } ], ``` 对象配置方式 ```js sidebar: { '/guide/': [ { text: 'Guide', items: [ { text: 'Index', link: '/guide/' }, // /guide/index.md { text: 'One', link: '/guide/one' }, // /guide/one.md { text: 'Two', link: '/guide/two' } // /guide/two.md ] } ] } ``` 1) 适合文档没有那么多的时候； 2) 能够更好的组织文档结构。对标如下页面： ![vitepress04.jpg](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5a08352fd3ad418c86e7314ff7debc99~tplv-k3u1fbpfcp-watermark.image?) ### 静态资源与导航路由的路径书写规则。 **静态资源**：推荐放入 `/docs/public` 文件夹中。随后在 `md` 中使用时以 `![image](/images/xxx.png)`。 `/` 以 `public` 开始。 **路径配置规则**：以 `/docs` 为根目录，进行配置；`/` 以 `docs` 开始。示例： ```js export default defineConfig({ themeConfig: { // link 点击时跳转的默认地址 // activeMatch 无论在 guide 下的哪一个子菜单都会保持高亮。 nav: [{ text: '指导', link: '/guide/what-is-vitepress', activeMatch: '/guide' }], sidebar: { '/guide/': [ { text: '介绍', items: [ { text: '什么是 VitePress', link: '/guide/what-is-vitepress' }, { text: '快速开始', link: '/guide/getting-started' }, { text: '配置', link: '/guide/configuration' }, { text: '发布', link: '/guide/deploying' } ], collapsible: true } ] } } }); ``` ![vitepress07.jpg](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2d624748a781485788b31ae67f49b0c7~tplv-k3u1fbpfcp-watermark.image?) ### 文章底部上下翻页、在 `Github` 编辑此页、最后更新时间 1. **上下翻页** 此功能虽是默认提供，也可以通过配置来定制默认的文字。 ```js export default { themeConfig: { docFooter: { prev: '上一篇', next: '下一篇' } } } ``` 2. **在 `Github` 编辑此页** 可以通过 `editLink` 来进行配置 `pattern`：可以分为两部分，`:path` 为变量内容指当前的文件名称。`:path` 之前的部分则是项目的 `/docs` 的 `github` 的文档地址。 ```js export default { themeConfig: { editLink: { pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', text: 'Edit this page on GitHub' } } } ``` 3. **最后更新时间** 需要在 `themeConfig` 平级去开启此选项，然后在 `themeConfig` 中可以去定制其展示文字。需要注意的是配置之后不会立即生效。 ```js export default { lastUpdated: true, themeConfig: { lastUpdatedText: "最近更新时间" } } ``` ### 其他全局配置信息 1. 主 `title` 内容与图片配置。 ```js export default defineConfig({ title: '自定义的 title', themeConfig: { logo: '/test.jpg', } }) ``` ![vitepress08.jpg](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e978c30575db4f9a8a55536144442e9f~tplv-k3u1fbpfcp-watermark.image?) 2. 打包后输出目录的配置 ```js export default { outDir: '../dist' } ``` 3. `markdown` 主题配置 [点击查看文档](https://vitepress.vuejs.org/config/app-configs#markdown) 4. `description` 配置后会显示页面中 `` 显示 ```js export default defineConfig({ description: '自定义的 description', }) ``` 5. `head` 配置后会显示在页面中的 `head` 中。可以配置多个。应该也能扩展 `VitePress` 的功能，有兴趣的可以研究下。 ```js export default defineConfig({ head: [['meta', { name: 'keywords', content: 'HTML, CSS, JavaScript' }]], }) ``` ![vitepress09.jpg](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6b8ee131d33243499393b05ef873358a~tplv-k3u1fbpfcp-watermark.image?) 6. 页脚通过 `footer` 进行配置。**如果 `Sidebar` 存在则页脚不会存在** ```js export default { themeConfig: { footer: { message: 'Released under the MIT License.', copyright: 'Copyright © 2019-present Evan You' } } } ``` ![vitepress10.jpg](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/edd49e0782ce41a68ec11806d2c1dd31~tplv-k3u1fbpfcp-watermark.image?) ## 国际化配置 1. 增加 `locales` 配置，修改语言环境以及 `title` 和 `description` 的国际化内容；此时可以去除上面配置的与 `locales` 平级的 `title` 和 `description`。 ```js export default defineConfig({ locales: { "/": { lang: "zh-CN", title: "自定义的 title", description: "自定义的 description" }, "/en/": { lang: "en-US", title: "Custom title", description: "Custom description" } }, }); ``` 2. 在 `themeConfig` 下增加 `localeLinks` 切换国际化的下拉框； ```js export default defineConfig({ themeConfig: { localeLinks: { items: [ { text: "简体中文", link: "/" }, { text: "English", link: "/en" } ] }, } }); ``` 3. 将 `themeConfig` 下的内容进行拆分并在 `/docs` 下新增 `/en` 文件夹用于存放国际化文档。 ```js export default defineConfig({ themeConfig: { locales: { // 函数功能就是将需要语言转换的内容分开成两套配置，后续有示例 "/": getChineseThemeConfig(), "/en/": getEnglishThemeConfig() }, } }) ``` 4. 具体示例代码以及项目结构演示； ```js export default defineConfig({ outDir: "../dist", head: [["meta", { name: "keywords", content: "HTML, CSS, JavaScript" }]], lastUpdated: true, locales: { "/": { lang: "zh-CN", title: "自定义的title", description: "自定义的description" }, "/en/": { lang: "en-US", title: "Custom title", description: "Custom description" } }, themeConfig: { logo: "/test.jpg", socialLinks: [{ icon: "github", link: "https://github.com" }], localeLinks: { text: "", items: [ { text: "中文", link: "/" }, { text: "English", link: "/en/" } ] }, locales: { // 原本 themeConfig 下所有需要转换的信息通过手动写两套配置的方式全部处理一下 // 例如 // 中文展示 docFooter: { prev: "上一页", next: "下一页" } // 英文展示 docFooter: { prev: "Pre page", next: "Next page" } "/": getChineseThemeConfig(), "/en/": getEnglishThemeConfig() } } }); // 注意英文配置下路径也需要进行处理。 function getEnglishThemeConfig() { return { nav: [{ text: "Guide", link: "/en/guide/what-is-vitepress", activeMatch: "/en/guide/" }], sidebar: { "/en/guide/": [ { text: "Description", items: [{ text: "What is VitePress", link: "/en/guide/what-is-vitepress" }], collapsible: true } ] }, // ... ... }; } ``` 国际化基本的目录结构应该如下这样； ``` . docs ├── en │ ├── guide │ │ └── what-is-vitepress.md │ └── index.md 英文状态下的 index 也需要进行转换 ├── guide │ └── what-is-vitepress.md ├── index.md ├── node_modules ``` ## 主题配置主题的配置可以分为两种。**拓展主题** **定制主题** 使用方式大体相同。 `.vitepress` 下新增 `theme` 文件夹以及 `/theme/index.js` 文件无论使用哪种方式，哪怕不定制主题，也可以单独的修改它默认的样式。 [查看样式定制](https://vitepress.vuejs.org/guide/theme-introduction#customizing-css) ```js // .vitepress/theme/index.js import DefaultTheme from 'vitepress/theme' import './custom.css' export default DefaultTheme ``` ```css /* .vitepress/theme/custom.css */ :root { --vp-c-brand: #646cff; --vp-c-brand-light: #747bff; } ``` ### 拓展主题使用 `vitepress` 提供的一些插槽拓展它的主题；[查看布局插槽](https://vitepress.vuejs.org/guide/theme-introduction#layout-slots) ```js // .vitepress/theme/index.js import DefaultTheme from 'vitepress/theme' import MyLayout from './MyLayout.vue' export default { ...DefaultTheme, // override the Layout with a wrapper component that // injects the slots Layout: MyLayout } ``` ```html ``` ### 定制主题目前 `Element-Plus` 就是采用这种方式来开发的文档站点。 [Element-Plus文档源码入口文件](https://github1s.com/element-plus/element-plus/blob/dev/docs/.vitepress/theme/index.ts) ```js // .vitepress/theme/index.js import Layout from './Layout.vue' export default { // 布局文件入口， Layout, // this is a Vue 3 functional component // 404 页面 NotFound: () => 'custom 404', enhanceApp({ app, router, siteData }) { // 这里可以注册组件等内容在可以在文档中做组件预览展示等功能。 } } ``` ## `Markdown` 语法拓展语法拓展文档请移步 [这里](https://vitepress.vuejs.org/guide/markdown) 。都是一些拓展语法比较简单。 ## `Markdown` 中使用 `Vue` 文档请移步 [这里](https://vitepress.vuejs.org/guide/using-vue#templating) 。 ### `Vue` 组件展示插件推荐几个插件，这里就不在演示 `Demo`。使用起来也是比较简单的； 1. [vitepress-doc-plugin](https://www.npmjs.com/package/vitepress-doc-plugin) 相对推荐 2. [vitepress-demo-editor](https://www.npmjs.com/package/vitepress-demo-editor) 可交互的 `demo` 操作。根据需求推荐 3. [vitepress-demo](https://github.com/xinlei3166/vitepress-demo) 比较推荐 ## `Github Page` 发布 1. 根目录新建 `deploy.sh` 文件。并复制以下内容稍微修改。 ```bash #!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 删除文件需要根据实际打包的目录进行删除 rm -rf docs/.vitepress/dist/ # 生成静态文件 yarn docs:build # 进入生成的文件夹 cd docs/.vitepress/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 如果发布到 https://.github.io 修改仓库地址 # git push -f git@github.com:/.github.io.git master:gh-pages cd - ``` 2. 创建 `github` 仓库。**注意 `Repository name` 和本地的 `base` 配置相同** ```js export default defineConfig({ base: '/your-github-repository/' }) ``` 3. `package.json` 中新增脚本并执行，虽然等个三两分钟直接访问 `https://your-github.github.io/your-github-repository/`。 ```json "scripts": { "docs:deploy": "bash deploy.sh" } ``` 如果遇到异常参考 [VuePress 搭建组件库文档](https://juejin.cn/post/7064746265266880549#heading-18) [VuePress 部署](https://vuepress.vuejs.org/zh/guide/deploy.html) ## `Algolia` 搜索 > 本章节参考 [VuePress 博客优化之开启 Algolia 全文搜索](https://segmentfault.com/a/1190000041480102)。 > > `Algolia` 开始之前务必通读 [文档](https://docsearch.algolia.com/docs/what-is-docsearch) > > > 如果确认要引入该搜索时，需要保证你的项目可以用于外网访问。比如 `githubpages` 1. 点击此链接进行 `key`，[`Algolia` 申请](https://docsearch.algolia.com/apply)，时间可能会比较漫长。官网说不超过 2 周。申请成功后就坐等邮件吧。 ![vitepress11.jpg](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8981c1daee074f30a69256f9a9e87766~tplv-k3u1fbpfcp-watermark.image?) 2. 收到邮件后回复 I am the maintainer of the website, I can modify the code ~ 3. 再次收到邮件可能包含以下内容 ![vitepress12.jpg](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ef625af0b25249afb9928b5b4852f342~tplv-k3u1fbpfcp-watermark.image?) 4. 在 `config.js` 中增加配置信息 ```js algolia: { apiKey: "aea12a0a4281c855b5d23789e868f378", indexName: "interview-questions-record", // 如果 Algolia 没有为你提供 `appId` ，使用 `BH4D9OD16A` 或者移除该配置项 appId: "XQYLP2L9WC" } ``` ## 结尾彩蛋 [查看完整配置信息](https://github.com/ShuQingX/interview-questions-record/blob/main/docs/.vitepress/config.js) 同时也和各位小伙伴分享一下，我前段时间总结的一些前端面试题。希望对正在找工作，即将找工作的一些小伙伴提供到帮助。[2022面试题汇总](https://github.com/ShuQingX/interview-questions-record) 如果内容有帮助到你，就点个 star 激励一下我吧。