vitepress 中文文档 🎉

我报名参加金石计划1期挑战——瓜分10万奖池，这是我的第一篇文章，点击查看活动详情

✨ 前言

前阵子把自己的技术网站从vuepress升级到了vitepress，在看文档时发现 vitepress 没有中文文档，于是乎就做了一个中文文档的版本，方便自己翻阅文档，也为后续研究vitepress源码做准备。目前全新的vitepress中文文档已发布，快点击加收藏查看吧：

vitepress 中文文档 🎉🎉🎉。

文档仓库

什么是vitepress

VitePress 是基于vite的vuepress兄弟版。特别适合写博客网站，技术文档，面试题网站，就有着它先天的优势。基本上现在vue官方团队的网站也都使用了vitepress，例如vuejs、vitejs、Vitest、vueuse...哦，还有vitepress官网自己😝。

不仅如此，它还有极易上手、构建速度快、开发体检佳等优点。并且，它开箱即用，目前正处于 alpha 阶段，配置和 API 可能会在小版本之间发生变化。

相比vuepress的改进点

构建

这个结果显而易见，使用vite可以带来：

• 更快的本地服务启动
• 更快的热更新
• 更快的打包（内部使用Rollup）

更小的页面体积

vitepress使用了vue3，基于Vue3的tree-shaking + Rollup 代码拆分达到了打包体积更小的效果

• 每个页面的每个请求不会发送元数据。 这将页面权重与页面总数分离。仅返回当前页面的元数据。客户端导航将同时获取新页面的组件和元数据。

• 不使用 vue-router，因为 VitePress 的需求非常简单和具体 - 使用简单的自定义router（200行以下代码）代替。

配置

VitePress 旨在减少当前 VuePress 的复杂性，并从其极简主义根源重新开始。

新特性

布局

vitepress内置了包括doc、home、page的文档布局，

如果你不想要任何布局，你可以通过frontmatter传递 layout: false。如果您想要一个完全可定制的登录页面(默认情况下没有任何侧边栏、导航栏或页脚)，这个选项很有用。

主题

VitePress 带有默认主题，并提供许多开箱即用的功能。主题涵盖了导航栏、侧边栏、上下页按钮、编辑链接、最近更新日期、列表、搜索、团队组件等多个功能。

使用自定义主题

你可以通过添加.vitepress/theme/index.ts 文件（“主题入口文件”）来启用自定义主题。

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

VitePress 自定义主题是一个只包含四个属性的对象，定义如下：

interface Theme {
  Layout: Component // Vue 3 component
  NotFound?: Component
  enhanceApp?: (ctx: EnhanceAppContext) => void
  setup?: () => void
}

主题入口文件应将主题作为其默认导出：

// .vitepress/theme/index.js
import Layout from './Layout.vue'

export default {
  Layout,
  NotFound: () => 'custom 404',
}

Layout 组件如下所示：

<!-- .vitepress/theme/Layout.vue -->
<template>
  <h1>Custom Layout!</h1>

  <!-- Content就是markdown渲染的位置 -->
  <Content />
</template>

默认导出是自定义主题的唯一方式。 在自定义主题中，它就像普通的 Vite + Vue 3 应用程序一样工作。

扩展默认主题

如果想扩展和自定义默认主题，可以从 vitepress/theme 导入它并在导出自定义主题中对其进行扩展。 以下是一些常见自定义的示例：

注册全局组件

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    // 注册一个全局组件
    app.component('MyGlobalComponent', /* ... */)
  }
}

由于我们使用 Vite，你还可以利用 Vite 的 全局导入特性 自动注册组件目录。

自定义 CSS

默认主题 CSS 可通过覆盖根元素的 CSS 变量进行自定义：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
}

这里可以看到支持的 默认的主题 CSS 变量.

Layout 组件插槽

默认主题 <Layout/> 组件有一些插槽，可用于在页面的某些位置注入内容。具体可以点击查看

还有主题颜色，支持亮/暗黑主题，例如下面这个好看的暗黑主题。

部署

执行 build 后默认会在(.vitepress/dist)生成构建的产物，然后就可以开始部署到服务器上了。

vitepress 官网提供了 github page 、gitlab page、firebase等多个服务器的部署方式。推荐使用github page，提供了github action的示例代码，基本一步到位。

我个人的文档网站就发布在github page，使用action自动部署，还不清楚怎么用github action自动部署自己的文档网站的可以看我之前的文章：用GitHub Action + VuePress自动化部署自己的文档网站。

怎么做贡献

目前vitepress还处在aplha阶段，更新比较频繁，并且目前还没有国际化的支持，想必很多人都会想为开源做贡献，这不就是一个很好的机会吗😏。