VitePress 介绍

VitePress 是由 Vue.js 官方团队开发的基于 Vite 的静态站点生成器，专为构建文档网站而设计。它结合了 Vite 的极速构建和 Vue 3 的现代化开发体验，提供了简单、快速、可扩展的文档构建解决方案。

核心特点

• 极速启动与热更新：基于 Vite，启动和构建速度非常快，提升开发效率。
• Vue 3 支持：可以在 Markdown 中直接使用 Vue 组件，增强文档的交互性。
• Markdown 扩展：支持 GitHub 风格的表格、Emoji、目录表（TOC）、自定义容器等扩展语法。
• 内置搜索功能：提供全文搜索功能，提升用户体验。
• 主题定制：支持自定义主题，满足个性化需求。

快速开始

https://vitepress.dev/guide/getting-started

1. 安装依赖

npm add -D vitepress

1. 创建文档目录

mkdir docs
echo '# Hello VitePress' > docs/index.md

2. 启动开发服务器

npx vitepress dev docs

3. 构建静态站点

npx vitepress build docs

Markdown 扩展

VitePress 提供了多种 Markdown 扩展，以下是常用的几种：

标题锚点

标题会自动应用锚点。可以使用 markdown.anchor 选项配置锚点的渲染。要为标题指定自定义锚点而不是使用自动生成的锚点，请向标题添加后缀：

# 使用自定义锚点 {#my-anchor}

内部链接

内部链接将转换为路由器链接，用于 SPA 导航。每个子目录中包含的每个 index.md 都会自动转换为 index.html，并具有相应的 URL /。

例如，给定以下目录结构：

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

在 foo/one.md 文件中使用：

[Home](/) <!-- 将用户导航至根目录下的 index.html -->
[foo](/foo/) <!-- 将用户导航至目录 foo 下的 index.html -->
[foo heading](./#heading) <!-- 将用户锚定到目录 foo 下的 index 文件中的一个标题上 -->
[bar - three](../bar/three) <!-- 可以省略扩展名 -->
[bar - three](../bar/three.md) <!-- 可以添加 .md -->
[bar - four](../bar/four.html) <!-- 或者可以添加 .html -->

自定义容器

可以通过自定义容器来创建提示框、警告框等：

::: tip
这是一个提示框
:::

::: warning
这是一个警告框
:::

::: danger
这是一个危险框
:::

代码块高亮

支持代码块的语法高亮，使用 shiki 实现，支持多语言。

```js
console.log('Hello, VitePress!')

### 表格

支持 GitHub 风格的表格：

```md
| 表头1 | 表头2 | 表头3 |
|-------|-------|-------|
| 单元格1 | 单元格2 | 单元格3 |
| 单元格4 | 单元格5 | 单元格6 |

Emoji

支持 Emoji 表情：

:tada: :100:

目录表（TOC）

支持自动生成目录表：

[[toc]]

部署

构建完成后，将 .vitepress/dist 目录下的文件部署到任意静态托管服务：

• GitHub Pages
• Netlify
• Vercel
• 自建 Nginx/Apache

示例：使用 GitHub Actions 自动化部署

# .github/workflows/deploy.yml
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 18
      - run: npm install
      - run: npx vitepress build docs
      - run: npx peaceiris/actions-gh-pages@v3 \
          with:
            publish_dir: ./docs/.vitepress/dist
            github_token: ${{ secrets.GITHUB_TOKEN }}

参考资源

• VitePress 官方文档
• VitePress 中文文档
• Markdown 扩展 - VitePress