VitePress 基本使用

date

May 6, 2025

slug

vitepress-basic

status

Published

什么是 VitePress？

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

快速开始

初始化

在终端中运行以下命令，初始化一个新的 VitePress 项目：

你会遇到以下提示，需要回答几个简单的问题：

这将创建一个名为 docs 的文件夹，并在其中生成基础配置文件和示例页面。

同时，package.json 中会自动添加以下脚本命令：

启动

进入项目目录，启动开发服务器：

现在，你可以在浏览器中访问 http://localhost:5173 查看你的文档网站了。

配置详解

基础配置

VitePress 的配置文件位于 .vitepress/config.mts。下面是一个简单的基础配置示例：

首页配置

VitePress 提供了内置的首页布局，可以通过 frontmatter 配置。以 EasyEditor 的首页为例：

多语言支持

VitePress 支持通过 locales 配置实现多语言站点。你可以将公共配置（如 logo、主题插件、搜索配置等）抽离到共享配置文件中，然后根据语言调整具体内容（如 nav 和 sidebar）。

VitePress 会自动合并 locales 下的语言特定配置与顶层配置。只需在子语言配置中填写差异部分。

多语言的目录结构：

存在 root 配置时（如英文为默认语言）：

没有 root 配置时（所有语言都在子目录中）：

导航栏配置

导航栏是网站的主要导航方式，可以包含多级菜单：

侧边栏配置

侧边栏通常按照页面路径进行分组：

高级用法

使用插件

VitePress 提供了丰富的插件系统，可以帮助扩展文档站点的功能和优化。EasyEditor 项目中使用了 vitepress-plugin-group-icons 插件，它主要用于在 Markdown 和 Vite 配置中统一管理和显示图标。

vitepress-plugin-group-icons 插件有两个主要部分：一个是 Markdown 插件，用于在 Markdown 内容中使用图标，另一个是 Vite 插件，用于处理图标的相关功能。

自定义头部元素

你可以在配置中添加自定义的 <head> 元素：

构建

构建文档：

默认情况下，构建输出会放在 .vitepress/dist 目录中，可以通过 outDir 配置更改：

构建后的文件可以部署到任何静态网站托管服务，如 GitHub Pages、Netlify、Vercel 等。

实用技巧

大纲配置

你可以控制右侧大纲显示的标题级别。默认情况下，VitePress 只显示 h2 级别的标题。

单页面配置

frontmatter 支持基于页面的配置。在每个 markdown 文件中，可以使用 frontmatter 配置来覆盖站点级别或主题级别的配置选项。此外，还有一些配置选项只能在 frontmatter 中定义。

你还可以在单个文档页面中自定义大纲显示，方法是在文档开头添加 outline 配置：

此配置会让文档展示更深层次的标题结构。

更多配置项可以查看 frontmatter 配置 | VitePress

总结

更多细节请查阅 VitePress 官方文档