VitePress 是一个基于 Vue 和 Vite 的静态网站生成器，特别适合用于创建文档网站。通过之前撰写 EasyEditor 的文档经验，我将带你了解 VitePress 的基本使用方法以及一些高级配置技巧。
什么是 VitePress？
VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。
快速开始
初始化
在终端中运行以下命令，初始化一个新的 VitePress 项目：
npx vitepress init
你会遇到以下提示，需要回答几个简单的问题：
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◇ Theme:
│ Default Theme
│
◇ Use TypeScript for config and theme files?
│ Yes
│
◇ Add VitePress npm scripts to package.json?
│ Yes
│
└ Done! Now run npm run docs:dev and start writing.
Tips:
- Make sure to add docs/.vitepress/dist and docs/.vitepress/cache to your .gitignore file.
这将创建一个名为 docs 的文件夹，并在其中生成基础配置文件和示例页面。
同时，package.json 中会自动添加以下脚本命令：
{
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
}
启动
进入项目目录，启动开发服务器：
pnpm docs:dev
现在，你可以在浏览器中访问 http://localhost:5173 查看你的文档网站了。
配置详解
基础配置
VitePress 的配置文件位于 .vitepress/config.mts。下面是一个简单的基础配置示例：
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
// defineConfig 是 VitePress 提供的配置函数
// 用来返回一个 VitePress 配置对象
export default defineConfig({
// 站点的标题，通常显示在浏览器标签上
title: 'My Docs',
// 站点的描述，用于 SEO 或浏览器预览
description: '我的文档网站',
themeConfig: {
// 配置网站顶部的导航栏
nav: [
// 导航项，包含文字和跳转的链接
{ text: '首页', link: '/' },
{ text: '指南', link: '/guide/' }
],
// 配置侧边栏
sidebar: {
// 侧边栏的路径和对应的页面链接
'/guide/': [
{ text: '介绍', link: '/guide/' },
{ text: '快速开始', link: '/guide/getting-started' }
]
}
}
})
首页配置
VitePress 提供了内置的首页布局，可以通过 frontmatter 配置。以 EasyEditor 的首页为例：
---
# 配置首页的布局类型
layout: home
# 首页的主标题
title: "EasyEditor: 用于构建可视化应用平台的插件化跨框架低代码引擎"
# hero 是首页的展示区，通常包含项目的名称、简介、图片和操作按钮
hero:
# hero 区域的主标题
name: EasyEditor
# hero 区域的副标题
text: 低代码引擎
# hero 区域的描述，用来简短说明产品或项目的特点
tagline: 用于构建可视化应用平台的插件化跨框架低代码引擎
# hero 区域的图片，支持 light 和 dark 模式
image:
light: /logo.svg # light 模式下显示的 logo
dark: /logo-dark.svg # dark 模式下显示的 logo
alt: EasyEditor # 图片的替代文本
# hero 区域的操作按钮
actions:
- theme: brand # 按钮的主题样式
text: 什么是 EasyEditor？ # 按钮文字
link: /guide/why # 按钮链接
- theme: alt
text: 快速开始
link: /guide/getting-started
- theme: alt
text: API 参考
link: /reference/overview
# features 是展示项目特点的部分
features:
- title: 解耦设计 # 特点的标题
icon: 🔌 # 特点图标，可以是 emoji 或自定义图标
details: 引擎核心与框架无关，支持多种框架渲染扩展 # 特点的描述
- title: 插件化架构
icon: 🧩
details: 灵活的插件系统设计，生命周期管理、热键绑定、类扩展机制、依赖注入...
---
多语言支持
VitePress 支持通过 locales 配置实现多语言站点。你可以将公共配置（如 logo、主题插件、搜索配置等）抽离到共享配置文件中，然后根据语言调整具体内容（如 nav 和 sidebar）。
VitePress 会自动合并 locales 下的语言特定配置与顶层配置。只需在子语言配置中填写差异部分。
import { defineConfig } from 'vitepress'
export default defineConfig({
// 公共配置（可抽离到 shared.ts）
locales: {
root: {
label: 'English',
lang: 'en'
},
fr: {
label: 'French',
lang: 'fr', // 设置 <html lang="fr">
link: '/fr/guide' // 显示在语言切换菜单中的链接（默认为 /fr/）
// 可以添加 fr 特定的 themeConfig、sidebar、nav 等配置
}
}
})
多语言的目录结构：
- 存在 root 配置时（如英文为默认语言）：
docs/
├─ fr/
│ └─ foo.md
├─ es/
│ └─ foo.md
├─ foo.md # 默认语言的页面（root）
- 没有 root 配置时（所有语言都在子目录中）：
docs/
├─ en/
│ ├─ foo.md
├─ es/
│ ├─ foo.md
├─ fr/
├─ foo.md
导航栏配置
导航栏是网站的主要导航方式，可以包含多级菜单：
const Nav: DefaultTheme.NavItem[] = [
{
text: '指南',
items: [
{
text: '入门指南',
items: [
{ text: '为什么选择', link: '/guide/why' },
{ text: '快速开始', link: '/guide/getting-started' }
],
},
{
text: '场景实践',
items: [
{ text: '大屏设计', link: '/guide/scenarios/dashboard/' },
{ text: '表单设计', link: '/guide/scenarios/form/' },
],
},
],
activeMatch: '^/guide/',
},
{
text: '原理',
items: [...DesignItems],
}
]
侧边栏配置
侧边栏通常按照页面路径进行分组：
const Sidebar: DefaultTheme.Sidebar = {
'/guide/': [
{
text: '入门指南',
items: GettingStartedGuides,
},
{
text: '扩展开发',
items: ExtensionGuides,
}
],
'/design/': DesignItems,
'/reference/': ReferenceItems,
高级用法
使用插件
VitePress 提供了丰富的插件系统，可以帮助扩展文档站点的功能和优化。EasyEditor 项目中使用了 vitepress-plugin-group-icons 插件，它主要用于在 Markdown 和 Vite 配置中统一管理和显示图标。
vitepress-plugin-group-icons 插件有两个主要部分：一个是 Markdown 插件，用于在 Markdown 内容中使用图标，另一个是 Vite 插件，用于处理图标的相关功能。
import { defineConfig } from 'vitepress'
import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons'
export const shared = defineConfig({
markdown: {
config(md) {
// 使用 groupIconMdPlugin 插件来处理 Markdown 中的图标
md.use(groupIconMdPlugin)
},
},
vite: {
plugins: [
// 使用 groupIconVitePlugin 插件来处理 Vite 中的图标配置
groupIconVitePlugin(),
],
},
})
自定义头部元素
你可以在配置中添加自定义的 <head> 元素：
head: [
['link', { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }],
['link', { rel: 'alternate icon', href: '/favicon.ico', type: 'image/png', sizes: '16x16' }],
['meta', { name: 'author', content: 'Your Name' }],
]
构建
构建文档：
pnpm docs:build
默认情况下，构建输出会放在 .vitepress/dist 目录中，可以通过 outDir 配置更改：
export const shared = defineConfig({
outDir: './dist',
})
构建后的文件可以部署到任何静态网站托管服务，如 GitHub Pages、Netlify、Vercel 等。
实用技巧
大纲配置
你可以控制右侧大纲显示的标题级别。默认情况下，VitePress 只显示 h2 级别的标题。
themeConfig: {
outline: [2, 3], // 只显示 h2 和 h3 标题
}
单页面配置
frontmatter 支持基于页面的配置。在每个 markdown 文件中，可以使用 frontmatter 配置来覆盖站点级别或主题级别的配置选项。此外，还有一些配置选项只能在 frontmatter 中定义。
你还可以在单个文档页面中自定义大纲显示，方法是在文档开头添加 outline 配置：
---
outline: deep
---
# Runtime API Examples
...
此配置会让文档展示更深层次的标题结构。
更多配置项可以查看 frontmatter 配置 | VitePress
总结
VitePress 是一个高效、易上手的静态文档生成工具，适合用于构建技术文档、项目文档等。通过本文的讲解，你应该已经了解了如何使用 VitePress 创建文档、配置站点和进行自定义。
更多细节请查阅 VitePress 官方文档
