VitePress

vitepress 是一个静态站点生成器，基于 Vue 3 的。
很多框架的文档都是基于 vitepress 生成的。
官方网址：vitepress

快速开始：

现在管理包主推 yarn 和 pnpm，所以推荐使用 pnpm 安装。

  • 创建项目
1
$ pnpm add vitepress@latest file-name
  • 初始化项目
1
2
3
4
$ pnpm vitepress init
$
$ # 过程中会有几个填空，默认就行
$ # 建议第一项写上文件名，便于管理之后的所有文档
  • 启动项目
1
$ pnpm run docs:dev

现在，vitepress 会在本地创建一个热重载服务器
一般访问localhost:5173就能访问文档站点了

配置

配置完成后站点才能更灵活。
配置文件在总目录下，默认目录：

1
2
3
4
5
├─ file-name
│ ├─ .vitepress
│ │ └─ config.js
│ └─ index.md
└─ package.json

配置文件config.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
export default defineConfig({
  lang: 'en-US',
  title: "主页面标题",
  description: "副标题（描述）",
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [标签],

    sidebar: [侧边栏],

    socialLinks: [社交链接],
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2025-present Evan You'
    }
    ...
  },
});

这里的配置路由是死的，并不能联动，想了解更多可以学习博主丁少华的博客：vitepress 动态导航

主题配置: 主页

VitePress 提供主页布局。
在目录 index.md 的 YAML front-matter 中定义 layout: home
并加上其他元数据。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
layout: home
hero:
  name: home title
  text: home subtitle
  tagline: Hero tagline
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
    text: Get Started
    link: /guide/getting-started
    ...
features:
  - title: Simplicity First
    details: Minimal setup with markdown-centered project structure helps you focus on writing.
  - title: Vue-Powered
    details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
---

任何包含 YAML frontmatter 块的 Markdown 文件都将由 gray-matter 处理。
Frontmatter 块必须位于在 Markdown 文件的顶部，必须是有效的 YAML 格式，放置在三点划线之间。
在三点划线之间，你可以设置预定义变量，甚至可以创建自定义变量。

这些变量可以通过$frontmatter 调用。

本地搜索

得益于 minisearch，VitePress 支持使用浏览器内索引进行模糊全文搜索。要启用此功能，只需在 .vitepress/config.ts 文件中将 themeConfig.search.provider 选项设置为 ‘local’ 即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { defineConfig } from "vitepress";

export default defineConfig({
  themeConfig: {
    search: {
      provider: "local",
      options: {
        miniSearch: {
          /**
           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
           */
          options: {
            /* ... */
          },
          /**
           * @type {import('minisearch').SearchOptions}
           * @default
           * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
           */
          searchOptions: {
            /* ... */
          },
        },
      },
    },
  },
});

更多配置项参考MiniSearch 文档