VitePress 1.0 正式版横空出世！来一份使用指南

前言

前不久，VitePress 1.0 版本正式发布！将近四年的开发终成正果。

当我们访问 Vue 、Vite 官网的时候，是不是都会被如此漂亮的官方文档所惊艳，没错，它们都是使用 VitePress 所构建的，除此之外，还有很多技术文档都是由 VitePress 构建的，如：Vue Router、Pinia、VueUse、Rollup等技术文档网站。

VitePress 的第一次 commit 提交于 2020年4月30日，如今 VitePress 1.0 版本正式发布，意味着将近四年的时间，VitePress 终于迎来了它的第一个正式版本。

概述

VitePress 是一个静态站点生成器（SSG） ，基于 Vite 和 Vue 前端框架构建。VitePress 支持获取用 Markdown 编写的内容，当然，你也可以书写 .vue 文件，对其应用主题，并生成可以轻松部署的静态 HTML 页面。

VitePress 主要用于文档、博客、档案和营销网站，其自带一个专门为技术文档设计的默认主题。同时，VitePress 还支持自定义主题，具有标准 Vite + Vue 应用程序的开发体验。

相比于传统的静态站点生成器，VitePress 生成的站点实际上是一个单页应用程序（SPA）。对任何页面的初次访问都将会是静态 HTML，随后页面加载 JavaScript，变成 Vue SPA 单页应用程序。用户在站点内浏览时，不会再触发整个页面的刷新。

VitePress 专注于内容 ，只需要书写 Markdown 语法，我们就可以轻松的创建美观的文档站点，同时，VitePress 底层由 Vite 提供支持，你可以享受闪电般的热更新，还可以使用基于 Vite 的生态插件。在自定义主题的时候，可以使用 Vue 构建自定义主题，也可以直接在 Markdown 中使用 Vue 语法和组件构建。

快速上手

注意：Node 版本需要在 18 以上

1. 我们先建一个文件夹，用于放置项目文件，比如就叫 vitepress-template，然后在文件夹中的终端命令行输入 npm init，初始化仓库。

2. 在文件夹根目录命令行终端输入 npm add -D vitepress 安装项目依赖。

3. 在你需要构建项目的文件夹中打开命令行终端，输入：npx vitepress init。

4. 这时候会有提示，按着步骤一步一步来就可以，当我们第一次使用的时候，按照默认的命令安装即可，其中，官方给我们提供了一套美观的内置主题，方便我们开箱即用。

5. 现在我们就可以打开文件夹，在命令行终端输入 npm run docs:dev 启动项目。

此时，我们在浏览器中输入 http://localhost:5173，便可以看到运行结果。

相关配置

文件目录

这是安装完成后的目录及文件，如果我们想使用 VitePress 建设一个独立的站点，现在这种结构就可以，也就是在当前目录中搭建站点。

如果是某一个项目的项目文档，官网建议在 ./docs 中建设站点，便于与其它项目分开。那么我们就以 ./docs 为例来配置项目。

同时，在 package.json 文件中也要做对应的修改，再次在终端命令行输入 npm run docs:dev 即可启动项目。

其中：

docs 文件夹可作为项目根目录。

.vitepress 文件夹是 VitePress 的配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

.vitepress/cache 文件夹是 VitePress 开发服务器缓存存储的目录。

.vitepress/dist 文件夹是 VitePress 生产构建输出生成的存储目录。

.vitepress/config.ts 文件是 VitePress 的配置文件，也是核心文件。

.vitepress 目录之外的所有 Markdown 文件被称为源文件，其中每个 .md 文件在相同的路径下都会被编译为 .html 文件。

值得注意的是 ，在 .gitignore 文件中应该添加 .vitepress，从而在 git 提交中忽略 .vitepress 中的内容，防止上传至 git。

站点配置

所有的关于 VitePress 的配置内容都在 .vitepress/config.ts 文件中，下面列举我们在使用 Vitepress 时一些常用的配置，官方提供多种配置方式，更多具体相关的配置请参考 VitePress 官网的站点配置。

导航栏

页面最顶部就是导航栏部分，包含站点标题，全局菜单链接等内容，导航栏显示 config.title 作为站点的标题，但是你可以在 themeConfig.siteTitle 中自定义标题文本，同时还可以自定义站点的图标，前提是图标需要放置在 public 目录中，并赋值该绝对路径。

export default defineConfig({
  themeConfig: {
    siteTitle: 'My Custom Title',
    logo: '/my-logo.svg'
  }
})

导航栏最重要的部分便是导航链接，它可以让我们迅速链接到指定页面，我们可以在 themeConfig.nav 中配置导航链接。

export default defineConfig({
  themeConfig: {
     nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/example/' },
      { text: 'Section', link: '/section/' }
    ]
  }
})

配置完后就会在导航部分显示导航链接。

我们还可以为其设置下拉菜单，来链接到更多的内容中去。

export default defineConfig({
  themeConfig: {
      nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/example/' },
      {
        text: 'Section',
        items: [
          { text: 'Item A', link: '/section/item-a' },
          { text: 'Item B', link: '/section/item-b' },
          { text: 'Item C', link: '/section/item-c' },
          { text: 'Item C', link: '/section/item-d' }
        ]
      }
    ]
  }
})

配置完后当鼠标移动到指定导航链接上就会显示下拉菜单。

侧边栏

侧边栏与导航栏一样，起着非常重要的作用，侧边栏在 themeConfig.sidebar 中进行配置，以数组的形式传入 sidebar ，其中 text 作为侧边栏导航的一个小标题，items 数组表示在该小标题下的多个导航链接。

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      },
      {
        text: 'Section Title A',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' }
        ]
      },
      {
        text: 'Section Title B',
        items: [
          { text: 'Item C', link: '/item-c' },
          { text: 'Item D', link: '/item-d' }
        ]
      }
    ]
  }
})

配置完就会在侧边栏显示相应的内容。

值得注意的是 ，link 的配置方式需要在最前面加上 /，就会链接到对应的 .md 文件，而在最后面也加上 /，就会链接到相应目录的 index.md 文件。

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          // 显示的是 `/guide/index.md` 页面
          { text: 'Introduction', link: '/guide/' }
        ]
      }
    ]
  }
})

但是，有时候我们可能需要创建单独的侧边栏，此时 .md 文件应该在一个文件夹中。

配置时应该以对象的形式传入sidebar。

export default defineConfig({
  themeConfig: {
    sidebar: {
    // 当用户位于 `example` 目录时，会显示此侧边栏
    '/example/': [
        {
          text: 'Examples',
          items: [
            { text: 'Examples', link: '/example/' },
            { text: 'Markdown Examples', link: '/example/markdown-examples' },
            { text: 'Runtime API Examples', link: '/example/api-examples' }
          ]
        }
      ]
    }
  }
})

在侧边栏的配置中添加 collapsed 选项，就会显示按钮来展开与折叠下面的每个部分，默认情况下是展开状态。

export default defineConfig({
  themeConfig: {
    sidebar: {
    // 当用户位于 `example` 目录时，会显示此侧边栏
    '/example/': [
        {
          text: 'Examples',
          collapsed: false, // 默认展开
          items: [
            { text: 'Examples', link: '/example/' },
            { text: 'Markdown Examples', link: '/example/markdown-examples' },
            { text: 'Runtime API Examples', link: '/example/api-examples' }
          ]
        }
      ]
    }
  }
})

配置完就会显示按钮，默认 false，就会是展开状态。

上下页链接

VitePress 支持我们自定义上下页的文本和链接 ，同样支持自定义出现在上一页和下一页链接上方的文本。

1. 自定义上下页的文本和链接

注意： 在 .md 文件最上方的 frontmatter 中配置，当 prev 为 false 的时候，就会隐藏上一页

---
prev:
  text: '自定义下一页的文本和链接'
  link: '/example/'
---

2. 自定义上下页上方的文本，对中文文档友好

export default defineConfig({
  themeConfig: {
    // 自定义配置上下页上方的文本
    docFooter: {
      prev: '上一页',
      next: '下一页'
    }
  }
})

配置好后就会显示文字下一页。

最后更新时间

VitePress 允许自定义上次更新的文本和日期格式。

export default defineConfig({
  themeConfig: {
    // 自定义配置上次更新的文本和日期格式
    lastUpdated: {
      text: '最后更新于',
      formatOptions: {
        dateStyle: 'short',
        timeStyle: 'medium'
      }
    }
  }
})

配置好后就会在页面显示最后更新于这个文本和对应的时间，前提是你必须 commit MarkDown 文件后才会显示。

另外还可以在 .md 文件上方使用 frontmatter 语法配置 lastUpdated: false 来单独禁用某个页面的最后更新时间。

---
lastUpdated: false
---

搜索

VitePress 支持配置本地搜索功能，使用浏览器内的索引进行模糊全文的搜索，配置如下：

export default defineConfig({
  themeConfig: {
   // 开启本地搜索
    search: {
      provider: 'local'
    }
  }
})

配置好后就会在顶部导航出现一个搜索框。

针对搜索这一功能，官方提供了多种配置，具体实现方式可参考官网搜索这一部分内容。

Markdown 扩展写作

VitePress 针对 Markdown 专门内置了其扩展语法，我们可以在 .md 文件中实现大部分的写作格式要求，像代码高亮、代码块、Emoji、frontmatter、自定义容器等等，VitePress 都给我们提供了丰富的语法格式来书写 Markdown 文件。

在 Markdown 中使用 Vue

除此之外，我们还可以在 Markdown 文件中使用 Vue 来增强我们的文本内容，这是因为在 VitePress 中，每个 Markdown 文件都会被编译为 HTML，并将其作为 Vue 单文件组件处理，固然我们可以在 Markdown 中使用任何 Vue 功能，包括使用组件。

---
hello: world
---

<script setup>
import { ref } from 'vue'
// 引用组件
import CustomComponent from '../../components/CustomComponent.vue'

const count = ref(0)
</script>

## Markdown Content

The count is: {{ count }}

<button :class="$style.button" @click="count++">Increment</button>

## 使用组件
<CustomComponent />

<style module>
.button {
  color: red;
  font-weight: bold;
}
</style>

值得注意的是，所有标签都应放在 frontmatter 中。

自定义主题

我们在创建 VitePress 项目的时候，官方给我们提供了一套默认的主题，一般情况下我们会在 config.themeConfig 中针对默认主题进行自定义配置，但是 VitePress 强大的地方在于我们可以自定义主题，不仅如此，还可以在默认主题的基础上，扩展主题，针对自定义这一方面的内容，可参考官网自定义主题这一部分内容进行学习。

总结

VitePress 给我们提供了开箱即用的功能，可以让我们快速构建出一个文档类网站，尤其是对于一门技术来说，使用文档是不可或缺的一部分，有了 VitePress，我们就可以轻松搭建一个技术说明文档。

我认为，学习 VitePress 除了一定要参考官方文档之外，更高效率的学习方法就是克隆（clone） VitePress 官方文档仓库或者 Vue 官方文档仓库到本地，然后参照它们的代码和官方文档进行对比性的学习。

当我们浏览官方文档的时候，同时也要看看它们是如何使用代码实现的，这时候我们便会豁然开朗，原来这个知识点是这样使用的，我们就知道如何做出一个像 VitePress 和 Vue 这样漂亮的文档类网站了，同时我们也可以参考它们实现自己的一个文档类站点。

本文只是对于 VitePress 一个简单的学习总结，还有很多使用方法没有列举出来，如果想单纯的做一个简单的站点，这些知识点足够，但是如果想做像 Vue 这样的综合性官方网站，还需要参考 VitePress 官网和结合 Vue 官网文档的源码学习更多的使用技巧，尤其是自定义主题这方面的内容。

参考

VitePress 中文官网