什么是 VitePress？

VitePress 是 VuePress 的小弟弟，但是vitepress是在 Vite 上构建的。

动机

主要是因为太慢！但是不怪 VuePress，怪 Webpack！

Vite 则非常好的解决了问题：

1.几乎实时的服务启动

2.根据需要编译页面

3.非常轻量快速的 HMR（热模块重载）

另外，本身 VuePress 一些设计问题一直没有时间去修复，正好这次做个大重构。

改进的地方

1.利用了 Vue 3 的改进的模板静态分析来尽可能字符串化静态内容

2.静态内容以字符串模式而不是渲染函数代码发送，JS 负载更便宜，注水（SSR 时生成 js 交互逻辑代码）也更快

3.这些优化仍然允许在 markdown 中混合使用 Vue 组件，编译器会帮你处理静态/动态分离工作

4.使用了 Vite

5.更快的 dev 服务器启动

6.更快的热更新

7.更快的构建（使用 Rollup）

更轻量的页面

Vue 3  + Rollup 代码分离 不会把所有页面的元数据都在一个请求中发送出去。客户端导航时再一起获得新页面的组件及元数据

其他不同点

1.VitePress 更武断且更少的配置。VitePress目标是缩减掉当前 VuePress 的复杂性并从其极简主义的根源重新开始

2.VitePress 是面向未来的：其目标浏览器是只支持原生 ES 模块导入的浏览器。其鼓励使用原始的 JavaScript 而不用转义以及使用 CSS 变量来主题化

将来这会是 VuePress 的下一版本么？

可能不会。避免影响 VuePress 当前的主题和插件生态，核心逻辑是更少的主题 API（倾向于 JavaScript API 而不是文件布局方式）且没有插件（所有的定制都在主题内）

开始

1.初始化目录及 index.md

take vitepress-starter
yarn init
yarn add --dev vitepress
mkdir && echo '# Hello VitePress' > docs/index.md

2.添加这些脚本到 package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}

3.本地启动服务

yarn docs:dev

配置

没有配置，页面就很简单，用户没法导航。 在 docs 目录下创建 .vitepress 目录即可开始设置配置

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

.vitepress/config.js 是配置 VitePress 站的必要的文件，其将导出一个 JavaScript 对象：

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

资源文件处理

可通过相对 URL 来指向资源文件：

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

所有引用的资源文件 在生产打包时，会被复制到 dist 目录并文件名会带上 hash 未被引用的资源文件不会被复制 图片资源小于 4kb 的会被 base64

公开文件

public 目录是个特殊的目录

用来放置你没有在任何 markdown 里面引用的资源文件 这个目录下的文件名不会被重命名加上 hash 值 引用该目录的资源需要直接使用根路径引用，比如 public/icon.png 文件则需要通过 /icon.png 引用

基础 URL

解决你的站点部署不是在根目录的情况。

以 domain.com/sub-path/ 为例：

设置 .vitepress/config.js 的 base 参数为 /sub-path/ （注意必须以 / 开头及结尾） 如果要引用 public 的图片，使用 $withBase （被注入到了 Vue 的原型了），这个可以同时用在主题组件及 Markdown 文件

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

Markdown 扩展

标题锚点

标题自动会产生锚点

锚点渲染可以通过 markdown.anchor 选项设置

链接

内部链接

每个子目录里的 index.md 会自动转换为 index.html, 并且访问路径是 /

举个例子：

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

假设你目前在 foo/one.md

[Home](/) <!-- 指向根 README.md -->
[foo](/foo/) <!-- 指向 foo 目录的 index.html -->
[foo heading](./#heading) <!-- 指向在 foo 目录的 README 文件中的某个标题 -->
[bar - three](../bar/three) <!--可以忽略文件后缀 -->
[bar - three](../bar/three.md) <!-- 也可以加上 .md -->
[bar - four](../bar/four.html) <!-- 或者加上 .html -->

页面后缀

页面及内部链接默认自动添加 .html 后缀。

外部链接

外部链接自动添加 target="_blank" rel="noopener noreferrer":

vuejs.org
VitePress on GitHub

Frontmatter

支持 YAML frontmatter

---

title: Blogging Like a Hacker lang: en-US

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 col2iscentered1600\ col 2 is centered 1600 col2iscentered12 zebra stripes are neat $1 #表情 输入

输出 🎉 💯

内容目录

[[toc]]

自定义容器

::: tip This is a tip :::

This is a warning

This is a dangerous warning

自定义标题

Danger zone, do not proceed

代码块内的语法高亮

VitePress 用 Prism 库来进行语法高亮， 加上语言标识即可，支持的语言列表

代码块内的行高亮

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

不只是单行高亮，还可以这样:

行范围：{5-8}, {3-10}, {10-17} 多行：{4,7,9} 行范围及多行混合等：{4,7-13,16,23-27,40}

显示行号

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

高级配置

VitePress 用 markdown-it 作为 Markdown 渲染器。 可以通过在 .vitepress/config.js 中使用 markdown 选项定制：

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },

    // options for markdown-it-toc
    toc: { includeLevel: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}

部署

以下内容有这些共同约定：

你的文档放着项目根目录的 docs 目录 使用默认的打包输出位置 (.vitepress/dist) VitePress 作为本地依赖安装在项目中，并且已经添加以下脚本

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}

构建文档

yarn docs:build # 将构建并存放结果到 `.vitepress/dist`
yarn docs:serve # 预览前面构建的结果，也就是启动一个静态文件服务

也可以更改静态文件服务端口

{
  "scripts": {
    "docs:serve": "vitepress serve docs --port 8080"
  }
}