## 什么是`VitePress`? > VitePress 是早期的 WIP!目前的重点是首先使 Vite 稳定和功能完整。目前还不建议在任何重要的情况下使用这个 VitePress 是 VuePress 的兄弟，它建立在 Vite 之上 > `vuePress=webpack+vue2`,`vitePress=vite+vue3` ### 动机我们喜欢 VuePress v1，但是由于构建在 Webpack 之上，对于一个只有几个页面的简单文档站点来说，启动开发服务器所花费的时间简直令人难以忍受。而且 HMR 更新也可能需要数秒才能反映到浏览器中作为参考，[Composition API RFC repo](https://github.com/vuejs/composition-api-rfc) 只有两个页面，但是启动服务器需要 4 秒，而在浏览器中反映任何编辑几乎需要 2 秒。从根本上说，这是因为 VuePress v1 在本质上是一个 Webpack 应用程序。即使只有两个页面，它也是一个完整的正在编译的 Webpack 项目(包括所有主题源文件)。更糟糕的是，当项目有很多页面时，服务器必须首先完全编译每个页面，然后才能显示任何内容顺便说一句，Vite 很好地解决了这些问题:服务器几乎立即启动，按需编译只编译所服务的页面，以及快速的 HMR。另外，随着时间的推移，我注意到 VuePress v1 中还有一些额外的设计问题，但由于需要大量的重构，一直没有时间来修复。现在，有了 Vite 和 Vue 3，真的是时候重新考虑“Vue 驱动的静态站点生成器” ### 在 VuePress v1 的改进 VuePress v1....有一些改进 ### 它使用的是 Vue 3 利用 Vue 3 改进的模板静态分析来尽可能严格地约束静态内容。静态内容以字符串文本的形式发送，而不是 JavaScript 呈现函数代码，因此 JS 有效负载解析起来更容易，`hydration`也变得更快。 > 客户端接到 SSR 响应之后，为了支持（基于 JavaScript 的）交互功能，仍然需要创建出组件树，与 SSR 渲染的 HTML 关联起来，并绑定相关的 DOM 事件，让页面变得可交互，这个过程称为 hydration 注意：应用优化的同时仍然允许用户在 markdown 内容中自由混合 Vue 组件–编译器会自动为您进行静态/动态分离，您无需考虑它。 ### 它使用 Vite 之下的优势 - 更快的开发服务器启动 - 更快的热更新 - 更快的构建(内部使用 Rollup) ### 更轻的页面 - Vue 3 摇树 + Rollup 代码拆分(摇掉代码中未引用部分（dead-code),production 模式下会自动使用 tree-shaking 打包时除去未引用的代码。作用是优化项目代码) - 不为每个请求的每个页面提供元数据。这样可以将页面权重从总页面数中分离出来。只发送当前页的元数据。客户端导航同时获取新页面的组件和元数据 - 不使用 vue-router，因为 VitePress 的需求非常简单和具体-使用一个简单的自定义路由器(低于 200 LOC)代替。 - (WIP) i18n 区域设置数据也应该按需获取。 ### 其他不同 VitePress 更多的是坚持自己想法和减少配置：VitePress 的目标是缩小当前 VuePress 的复杂性，并从它的最简主义根源重新开始。 VitePress 是面向未来的:VitePress 只针对支持原生 ES 模块导入的浏览器。它鼓励使用不需要翻译的本地 JavaScript 和用于主题化的 CSS 变量。 ### 这会成为未来的下一个 VuePress 吗？我们已经有了 [VuePress -next](https://github.com/vuepress/vuepress-next)，这将是 VuePress 的下一个主要版本。它还比 VuePress v1 做了很多改进，现在还支持 Vite。VitePress 不兼容当前的 VuePress 生态系统(主要是主题和插件)。总体想法是，VitePress 将拥有一个更简约的主题 API(更喜欢 JavaScript API 而不是文件布局约定)，并且可能没有插件(所有定制都在主题中完成)。 ## 入门本节将帮助您从头开始构建一个基本的 VitePress 文档站点。如果您已经有了一个现有的项目，并且希望将文档保存在项目中，那么从步骤 3 开始。步骤 1:创建并更改到一个新目录。 ``` mkdir vitepress-starter && cd vitepress-starter ``` 步骤 2:用首选`yarn`包管理器初始化。 ``` yarn init ``` 步骤 3:本地安装 VitePress ``` yarn add --dev vitepress ``` 步骤 4:创建您的第一个文档 ``` mkdir docs && echo '# Hello VitePress' > docs/index.md ``` 步骤 5:向 package.json 中添加一些脚本。 ``` { "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:serve": "vitepress serve docs" } } ``` 步骤 6:在本地服务器上提供文档站点。 ``` $ yarn run docs:dev ``` 到目前为止，您应该已经有了一个基本但功能强大的 VitePress 文档站点。当您的文档站点开始形成时，[请务必阅读部署指南](https://vitepress.vuejs.org/guide/deploy.html)。 ## 结构没有任何配置，页面非常小，用户无法在站点周围导航。为了定制你的站点，让我们首先在 docs 目录中创建一个。vitepress 目录。这是所有特定于 vitepress 的文件将被放置的地方。您的项目结构可能是这样的 ``` . ├─ docs │ ├─ .vitepress │ │ └─ config.js │ └─ index.md └─ package.json ``` ![image.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1400169443d64898bf8ba9ce1c92d545~tplv-k3u1fbpfcp-watermark.image) 配置 VitePress 站点的基本文件是.VitePress/config.js，它应该导出一个 JavaScript 对象： ``` module.exports = { title: 'Hello VitePress', description: 'Just playing around.' } ``` ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b0f455a924d74e72a57bff5b0f4e37aa~tplv-k3u1fbpfcp-watermark.image) 查看[配置参考](https://vitepress.vuejs.org/config/basics.html)以获得完整的选项列表 ## 资源处理 ### 相对路径所有的 Markdown 文件都会被 webpack 编译成 Vue 组件，因此你可以，并且应该更倾向于使用相对路径（Relative URLs）来引用所有的静态资源： > 文件需要放到`docs`下，不然图片显示不出来 ``` ![An image](./image.png) ``` ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b13cebb1cb214a799da26f79b5b4d73d~tplv-k3u1fbpfcp-watermark.image) 你可以在你的 markdown 文件中引用静态资产。使用绝对公共路径(基于项目根目录)或相对路径(基于您的文件系统)的主题、样式和普通的`.css` 文件中的 Vue 组件。如果您使用过 vue-cli 或 webpack 的文件加载器`file-load`，后者类似于您所习惯的行为。常见的图像、媒体和字体文件类型将被自动检测并作为资产包括进来。所有引用的资源，包括那些使用绝对路径的资源，都将被复制到生产版本中带有哈希文件名的 dist 文件夹中。从未引用过的资产将不会被复制。与 vue-cli 类似，小于 4kb 的图像资产将采用 base64 内联。 ### 公共文件有时你可能需要提供静态资产，这些资产不会直接被你的 Markdown 或主题组件引用(例如，favicons 和 PWA icons)。项目根目录下的公共目录可以用作一个逃生出口，以提供静态资产，这些资产要么永远不会在源代码中引用(例如 robots.txt)，要么必须保持完全相同的文件名(没有散列)。放置在公共位置的资产将原样复制到 dist 目录的根目录中。请注意，应该使用根`绝对路径`引用公共文件-例如，public/icon.png 在源代码中应始终作为/icon.png 引用。 ### 基础路径如果站点部署到非根 URL，则需要在.vitepress/config.js 中设置 base 选项。例如，如果您计划将站点部署到https://foo.github.io/bar/，则应将base设置为“/bar/”（始终以斜杠开头和结尾）。对于基本 URL，要在公共场合引用图像，必须使用/bar/image.png 这样的 URL。但如果你决定改变基础，这是脆弱的。为了帮助实现这一点，VitePress 提供了一个内置的助手$withBase（注入到 Vue 的原型中），它可以生成正确的路径： ``` foo

``` ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e9b8059aa2014e7595d6d2abc4174bba~tplv-k3u1fbpfcp-watermark.image) ## Markdown 拓展 ### Header Anchors 所有的标题将会自动地应用 anchor 链接，anchor 的渲染可以通过 markdown.anchor 来配置。 ### 链接 #### 内部连接内部链接转换为路由器链接，用于 SPA 导航。此外，每个子目录中包含的每个 index.md 都将自动转换为 index.html，并带有相应的 URL/。例如，给定以下目录结构： ``` . ├─ index.md ├─ foo │ ├─ index.md │ ├─ one.md │ └─ two.md └─ bar ├─ index.md ├─ three.md └─ four.md ``` 提供其中之一 `foo/one.md` ``` [Home](/) [foo](/foo/) [foo heading](./#heading) [bar - three](../bar/three.md) [bar - four](../bar/four.html) ``` ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f83b8e7cdbb94534ba675db761882118~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/146c76741cf84cd883986747c96cd66e~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/66c1c8c598ce43b9b306cebfce74a47a~tplv-k3u1fbpfcp-watermark.image) #### 页面后缀默认情况下，生成的页面和内部链接的后缀是.html。 #### 外部链接出站的链接自动获得`target=" blank" rel="noopener noreferrer` ### 前言 [YAML frontmatter 外网](https://jekyllrb.com/docs/frontmatter/) 支持开箱即用： > 注意的是采用三虚线必须放置在 markdown 文件的最上面 ``` --- title: Blogging Like a Hacker lang: en-US --- ``` #### `frontmatter` ##### 可供选择的 frontmatter 格式任何包含 YAML frontmatter 块的 Markdown 文件都将被 gray matter 处理。frontmatter 必须位于 Markdown 文件的顶部，并且必须采用三条虚线之间的有效 YAML 集的形式。例子： > $frontmatter 很重要，vitePress 只识别这个----三条虚线块有且只有一个 ``` --- title: tags date: 2019-08-13 09:39:50 type: tags layout: tag --- # Hello VitePress # {{ $frontmatter.date }} ``` 在三虚线之间，您可以设置预定义的变量，甚至创建您自己的自定义变量。这些变量可以通过`$frontmatter `变量来使用。这里有一个例子，你可以在你的 Markdown 文件中使用它 VitePress 还支持 JSON 前端语法，以花括号开始和结束【俩种写法不能共存】 ``` --- { "title": "Blogging Like a Hacker", "editLink": true } --- # {{ $frontmatter.title }} ``` ##### 预定义的变量 https://vitepress.vuejs.org/guide/frontmatter.html#predefined-variables - title (default h1_title || siteData.title): 当前页面的标题 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/514ce1441abd4fd6b2ce54ae07eb3af0~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d3db1b4f97174d74b4159f529597145e~tplv-k3u1fbpfcp-watermark.image) - head (default undefined): 指定要注入的额外头标记： ``` --- head: - - meta - name: description content: hello - - meta - name: keywords content: super duper SEO --- ``` ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/cd6981ea00884e509e36126f28e61cea~tplv-k3u1fbpfcp-watermark.image) - navbar(default undefined): 你可以用导航栏:false 来禁用特定页面上的导航栏头部消失 ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/21590c0eb5af4d7fa3df9a14f69336d7~tplv-k3u1fbpfcp-watermark.image) - sidebar(default undefined): 你可以决定在一个特定的页面上用 sidebar: auto 显示 sidebar，或者用 sidebar: false 禁用它左边消失 ![image.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6f71bd35272f4abbb4ebccb17455f718~tplv-k3u1fbpfcp-watermark.image) - editLink(default undefined): 定义此页是否应该包含编辑链接 - date: 这里的日期会覆盖帖子名称中的日期。这可以用来确保正确排序的职位。日期的格式为 YYYY-MM-DD HH:MM:SS+/-TTTT；小时、分钟、秒和时区偏移是可选的。 - tags: 类似于类别，一个或多个标签可以添加到一个帖子。与类别一样，标记也可以指定为 YAML 列表或空格分隔的字符串。该数据对页面的其余部分以及所有自定义和主题化组件都可用。详情请参阅 [Frontmatter](https://vitepress.vuejs.org/guide/frontmatter.html) #### GitHub 风格的表格 - 表 ``` | Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 | ``` 输出 | Tables | Are | Cool | | ------------- | :-----------: | ----: | | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 | - 表情 ``` :tada: :100: ``` 输出 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/aaee078e79ee49bd8b1520a5082972a1~tplv-k3u1fbpfcp-watermark.image) - 内容目录 ``` [[toc]] ``` 输出 ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7b6f1d9548d3442793ec6df0b333496a~tplv-k3u1fbpfcp-watermark.image) 目录（Table of Contents）的渲染可以通过 markdown.toc 选项来配置。 #### 自定义容器自定义容器可以通过它们的类型、标题和内容来定义默认提示 ``` ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning ::: ``` 输出 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b58ddaacb34e4f38a2955cf6cdb5f6df~tplv-k3u1fbpfcp-watermark.image) 自定义提示 ``` ::: danger STOPxxxxxx Danger zone, do not proceed ::: ``` 输出 ![image.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a0ddf91f3c3f4eb2869aedb036aec31a~tplv-k3u1fbpfcp-watermark.image) #### 代码块中的语法高亮显示 ```` ```js export default { name: 'MyComponent', // ... } ``` ```` 输出 ``` export default { name: 'MyComponent' // ... } ``` ```` ```html

{{ todo.text }}

``` ```` 输出 ```html

{{ todo.text }}

``` [Prism 网站上](https://prismjs.com/#languages-list)有有效语言的列表。 ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6d13b05a8aad453581a7810fe02c5cb8~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/87e9969147634ad3a7c2c7bb0ab38fd6~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5bdf5da174bb4d1c822087d45879340a~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9c89b22e234545c89a5d892ed840df14~tplv-k3u1fbpfcp-watermark.image) #### 代码块中的行高亮显示 ```` ```js{4} export default { data () { return { msg: 'Highlighted!' } } } ``` ```` 输出 ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6a2dda3f4fbf4eeca05d6899beb92c05~tplv-k3u1fbpfcp-watermark.image) 除了单行之外，您还可以指定多个单行、范围或同时指定 - 行范围:例如{5-8}，{3-10}，{10-17} - 多个单行:例如{4,7,9} - 行范围和单行:例如{4,7-13,16,23-27,40} ```` ```js{1,4,6-7} export default { // Highlighted data () { return { msg: `Highlighted! This line isn't highlighted, but this and the next 2 are.`, motd: 'VitePress is awesome', lorem: 'ipsum', } } } ```` 输出 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1a6a4e76c2e24a38ab613c9780e6bedb~tplv-k3u1fbpfcp-watermark.image) #### 行号您可以通过 config 为每个代码块启用行号 ``` module.exports = { markdown: { lineNumbers: true } } ``` #### 导入代码片段您可以通过以下语法从现有文件导入代码片段 ``` <<< @/filepath ``` ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ff63d07973e44dd08f9593ff5be9155a~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5c511437c8dd4821b14398799aa99c08~tplv-k3u1fbpfcp-watermark.image) 它还支持行高亮显示 ``` <<< @/filepath{highlightLines} ``` ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2affae78db5a45228c80af4edca851d6~tplv-k3u1fbpfcp-watermark.image) ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3924fb0f20d44dc09e8e82631699aa14~tplv-k3u1fbpfcp-watermark.image) ``` 此处的 @ 默认值是 process.cwd()。 ``` 你也可以使用 VS Code 区域只包含代码文件的相应部分。您可以在文件路径后面的#后面提供自定义区域名称(默认情况下是代码片段) #### 进阶配置 VitePress 使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一步的话，你可以通过 .vitepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例做一些自定义的配置： ``` module.exports = { markdown: { // markdown-it-anchor 的选项 anchor: { permalink: false }, // markdown-it-toc 的选项 toc: { includeLevel: [1, 2] }, config: (md) => { // 使用更多的 markdown-it 插件! md.use(require('markdown-it-xxx')) } } } ``` ### 在 Markdown 中使用 Vue #### 浏览器的 API 访问限制当你在开发一个 VitePress 应用时，由于所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染，因此所有的 Vue 相关代码都应当遵循编写通用代码的要求。简而言之，请确保只在 beforeMount 或者 mounted 访问浏览器 / DOM 的 API。如果您正在使用或演示的组件不是 ssr 友好的(例如，包含自定义指令)，您可以将它们包装在内置的组件中 ``` ``` 请注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入它们 ``` ``` 如果你的模块导出了一个默认的 Vue 组件，你可以动态注册它 ``` ``` https://v3.cn.vuejs.org/guide/component-dynamic-async.html#%E5%9C%A8%E5%8A%A8%E6%80%81%E7%BB%84%E4%BB%B6%E4%B8%8A%E4%BD%BF%E7%94%A8-keep-alive #### 模板语法 ##### 插值每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 vue-loader，这意味着你可以在文本中使用 Vue 风格的插值： ``` {{ 1 + 1 }} ``` 输出 ``` 2 ``` ##### 指令同样地，也可以使用指令: ``` {{ i }} ``` 输出 ``` 123 ``` ##### 访问网站以及页面的数据 ``` {{ $page }} ``` 输出 ``` { "title": "tagsadsandbsamnbdmnasbdnmasbd", "description": "hello", "frontmatter": { "title": "tagsadsandbsamnbdmnasbdnmasbd", "editLink": true, "tags": "dd", "head": [ [ "meta", { "name": "description", "content": "hello" } ], [ "meta", { "name": "keywords", "content": "super duper SEO" } ] ] }, "relativePath": "index.md", "lastUpdated": 1621777101000 } ``` #### Escaping 默认情况下，块级 (block) 的代码块将会被自动包裹在 v-pre 中。如果你想要在内联 (inline) 的代码块或者普通文本中显示原始的大括号，或者一些 Vue 特定的语法，你需要使用自定义容器 v-pre 来包裹： ``` ::: v-pre `{{ This will be displayed as-is }}` ::: ``` 输出 ![image.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/24ca7e9e962549afa322788b4a00d7e4~tplv-k3u1fbpfcp-watermark.image) #### 使用组件当你需要更多的灵活性时，VitePress 允许你用自己的 Vue 组件扩展你的创作工具箱。 ##### 低价导入组件如果您的组件将只在少数地方使用，那么推荐的使用方法是在使用它的文件中导入组件。 ``` # Docs This is a .md using a custom component ## More docs ... ``` ##### 在主题中注册全局组件如果这些组件将在文档中的多个页面中使用，它们可以在主题中全局注册(或者作为扩展默认 VitePress 主题的一部分)。[查看定制指南](https://vitepress.vuejs.org/guide/customization.html)获取更多信息。在.vitepress/theme/index.js 中，enhanceApp 函数接收 Vue 应用程序实例，以便您可以像在常规 Vue 应用程序中一样注册组件。 ``` import DefaultTheme from 'vitepress/theme' export default { ...DefaultTheme, enhanceApp({ app }) { app.component('VueClickAwayExample', VueClickAwayExample) } } ``` 稍后在您的标记文件中，组件可以在内容之间交错 ``` # Vue Click Away ``` > 重要:请确保一个自定义组件的名字包含连接符或者是 PascalCase，否则，它将会被视为一个内联元素，并被包裹在一个

标签中，这将会导致 HTML 渲染紊乱，因为 HTML 标准规定，

标签中不允许放置任何块级元素。 ##### 在标题中使用组件 | **Markdown** | **输出的 HTML** | **解析后的标题** | | ------------------ | :----------------------------------------: | ---------------: | | `# text ` | `

text

` | `text` | | `# text `` ` | `

text `<Tag/>`

` | `text ` | ``` 由

封装的 HTML 将按原样显示;只有没有包装的 HTML 才会被 Vue 解析。
```

> 输出的 HTML 由 markdown-it 完成。而解析后的标题由 VuePress 完成，用于侧边栏以及文档的标题。

#### 使用预处理器

VitePress 内置了对 CSS 预处理器的支持:.scss， .sass， .less， . style 和.stylus 文件。不需要为它们安装特定于 vite 的插件，但是必须安装相应的预处理器本身

```
# .scss and .sass
npm install -D sass

# .less
npm install -D less

# .styl and .stylus
npm install -D stylus
```

然后您可以在 Markdown 和主题组件中使用以下内容

```

```

#### 脚本和样式提升

```
有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中使用原生的

text

text <Tag/>

text `<Tag/>`