VitePress 学习(全面拥抱vite)---翻译

什么是VitePress?

VitePress 是早期的 WIP!目前的重点是首先使 Vite 稳定和功能完整。目前还不建议在任何重要的情况下使用这个

VitePress 是 VuePress 的兄弟，它建立在 Vite 之上

vuePress=webpack+vue2,vitePress=vite+vue3

动机

我们喜欢 VuePress v1，但是由于构建在 Webpack 之上，对于一个只有几个页面的简单文档站点来说，启动开发服务器所花费的时间简直令人难以忍受。而且 HMR 更新也可能需要数秒才能反映到浏览器中

作为参考，Composition API RFC repo 只有两个页面，但是启动服务器需要 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 之下的优势更轻的页面其他不同

VitePress 更多的是坚持自己想法和减少配置：VitePress 的目标是缩小当前 VuePress 的复杂性，并从它的最简主义根源重新开始。

VitePress 是面向未来的:VitePress 只针对支持原生 ES 模块导入的浏览器。它鼓励使用不需要翻译的本地 JavaScript 和用于主题化的 CSS 变量。

这会成为未来的下一个 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 文档站点。

当您的文档站点开始形成时，请务必阅读部署指南。

结构

没有任何配置，页面非常小，用户无法在站点周围导航。为了定制你的站点，让我们首先在 docs 目录中创建一个。vitepress 目录。

这是所有特定于 vitepress 的文件将被放置的地方。您的项目结构可能是这样的

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json

配置 VitePress 站点的基本文件是.VitePress/config.js，它应该导出一个 JavaScript 对象：

module.exports = {
  title: 'Hello VitePress',
  description: 'Just playing around.'}

查看配置参考以获得完整的选项列表

资源处理相对路径

所有的 Markdown 文件都会被 webpack 编译成 Vue 组件，因此你可以，并且应该更倾向于使用相对路径（Relative URLs）来引用所有的静态资源：

文件需要放到docs下，不然图片显示不出来

![An image](./image.png)

你可以在你的 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 选项。例如，如果您计划将站点部署到foo.github.io/bar/，则应将bas…

对于基本 URL，要在公共场合引用图像，必须使用/bar/image.png 这样的 URL。但如果你决定改变基础，这是脆弱的。为了帮助实现这一点，VitePress 提供了一个内置的助手$withBase（注入到 Vue 的原型中），它可以生成正确的路径：

src="$withBase('/foo.png')" alt="foo" />

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)

页面后缀

默认情况下，生成的页面和内部链接的后缀是.html。

外部链接

出站的链接自动获得target=" blank"heading-20">前言

YAML frontmatter 外网 支持开箱即用：

注意的是采用三虚线必须放置在 markdown 文件的 最上面

---title: Blogging Like a Hackerlang: en-US---

frontmatter可供选择的 frontmatter 格式

任何包含 YAML frontmatter 块的 Markdown 文件都将被 gray matter 处理。frontmatter 必须位于 Markdown 文件的顶部，并且必须采用三条虚线之间的有效 YAML 集的形式。例子：

$frontmatter 很重要，vitePress 只识别这个----三条虚线块有且只有一个

---title: tagsdate: 2019-08-13 09:39:50type: tagslayout: tag---# Hello VitePress# {{ $frontmatter.date }}

在三虚线之间，您可以设置预定义的变量，甚至创建您自己的自定义变量。这些变量可以通过$frontmatter 变量来使用。这里有一个例子，你可以在你的 Markdown 文件中使用它

VitePress 还支持 JSON 前端语法，以花括号开始和结束【俩种写法不能共存】

---{  "title": "Blogging Like a Hacker",  "editLink": true}---# {{ $frontmatter.title }}

预定义的变量

---head:
  - - meta- name: description  content: hello
  - - meta- name: keywords  content: super duper SEO---

头部消失

左边消失

该数据对页面的其余部分以及所有自定义和主题化组件都可用。

详情请参阅 Frontmatter

GitHub 风格的表格

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

输出

TablesAreCool

col 3 is

right-aligned

$1600

col 2 is

centered

$12

zebra stripes

are neat

$1

:tada: :100:

输出

[[toc]]

输出

目录（Table of Contents）的渲染可以通过 markdown.toc 选项来配置。

自定义容器

自定义容器可以通过它们的类型、标题和内容来定义

默认提示

::: tipThis is a tip:::::: warningThis is a warning:::::: dangerThis is a dangerous warning:::

输出

自定义提示

::: danger STOPxxxxxxDanger zone, do not proceed:::

输出

代码块中的语法高亮显示

```jsexport default {
  name: 'MyComponent',  // ...}
```

输出

export default {
  name: 'MyComponent'
  // ...}

```html<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  li>
ul>
```

输出

<ul>
  <li v-for="todo in todos" :key="todo.id">{{ todo.text }}li>ul>

有有效语言的列表。

代码块中的行高亮显示

```js{4}export default {  data () {return {
      msg: 'Highlighted!'}
  }
}
```

输出

除了单行之外，您还可以指定多个单行、范围或同时指定

```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',
    }
  }
}

输出

行号

您可以通过 config 为每个代码块启用行号

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

导入代码片段

您可以通过以下语法从现有文件导入代码片段

<<< @/filepath

它还支持行高亮显示

<<< @/filepath{highlightLines}

此处的 @ 默认值是 process.cwd()。

你也可以使用 VS Code 区域只包含代码文件的相应部分。您可以在文件路径后面的#后面提供自定义区域名称(默认情况下是代码片段)

进阶配置

VitePress 使用 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 友好的(例如，包含自定义指令)，您可以将它们包装在内置的组件中

<ClientOnly>
  <NonSSRFriendlyComponent/>ClientOnly>

请注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入它们

<script>export default {
  mounted () {import('./lib-that-access-window-on-import').then(module => {      // use code})
  }
}script>

如果你的模块导出了一个默认的 Vue 组件，你可以动态注册它

<template>
  <component v-if="dynamicComponent" :is="dynamicComponent">component>template><script>export default {  data() {return {      dynamicComponent: null}
  },
  mounted () {import('./lib-that-access-window-on-import').then(module => {      this.dynamicComponent = module.default})
  }
}script>

模板语法插值

每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 vue-loader，这意味着你可以在文本中使用 Vue 风格的插值：

{{ 1 + 1 }}

输出

2

指令

同样地，也可以使用指令:

<span v-for="i in 3">{{ i }} span>

输出

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 }}`
:::

输出

使用组件

当你需要更多的灵活性时，VitePress 允许你用自己的 Vue 组件扩展你的创作工具箱。

低价导入组件

如果您的组件将只在少数地方使用，那么推荐的使用方法是在使用它的文件中导入组件。

# Docs
This is a .md using a custom component<CustomComponent />## More docs
...<script setup>import CustomComponent from '../components/CustomComponent.vue'script>

在主题中注册全局组件

如果这些组件将在文档中的多个页面中使用，它们可以在主题中全局注册(或者作为扩展默认 VitePress 主题的一部分)。查看定制指南获取更多信息。

在.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

text

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

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

使用预处理器

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

# .scss and .sassnpm install -D sass# .lessnpm install -D less# .styl and .stylusnpm install -D stylus

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

<style lang="sass">.title
  font-size: 20pxstyle>

脚本和样式提升

有时，你可以只想在当前页面应用一些 JavaScript 或者 CSS，在这种情况下，你可以直接在 Markdown 文件中使用原生的 <script> 或者 <style> 标签，它们将会从编译后的 HTML 文件中提取出来，并作为生成的 Vue 单文件组件的 <script> 和 <style> 标签

内置组件

VitePress 提供内置的 Vue 组件，如 ClientOnly 和 OutboundLink，查看全局组件指南了解更多信息。

部署

「小礼物走一走？华子可乐来一个！」

赞赏

还没有人赞赏，支持一下吧

×

哇~真是太棒了 感谢大佬支持

可乐华子奶茶傍一矿泉水