VitePress 静态文档框架¶

一句话概述：VitePress 是 Vue 团队出品的文档生成器，基于 Vite 构建，启动秒开、热更新极快，适合 Vue 生态项目文档。

核心知识点¶

概念	白话解释
VitePress	Vue 版文档生成器 = Vite 驱动的静态文档
Vite	新一代构建工具 = 极速开发服务器
Frontmatter	文件头信息 = YAML 格式的页面配置
Theme	主题 = 默认主题已经很漂亮
SSG	静态站点生成 = 构建时生成 HTML

安装配置¶

# 前置要求：Node.js >= 18
mkdir my-docs && cd my-docs                            # 创建项目目录
npm init -y                                           # 初始化 package.json

# 安装 VitePress
npm install -D vitepress                               # 安装为开发依赖

# 初始化项目
npx vitepress init                                    # 交互式初始化

# 启动开发服务器
npx vitepress dev                                     # 本地预览（极速启动）

配置文件¶

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '我的文档',                                    // 网站标题
  description: '项目技术文档',                           // 描述
  lang: 'zh-CN',                                      // 语言

  themeConfig: {
    nav: [                                             // 顶部导航
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' },
    ],
    sidebar: [                                         // 侧边栏
      {
        text: '入门',
        items: [
          { text: '简介', link: '/guide/intro' },
          { text: '安装', link: '/guide/install' },
        ]
      }
    ],
    socialLinks: [                                     // 社交链接
      { icon: 'github', link: 'https://github.com/...' }
    ],
    search: { provider: 'local' },                     // 本地搜索
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024-present'
    }
  }
})

写文档¶

---
title: 快速开始
outline: [2, 3]
---

# 快速开始

VitePress 支持标准 Markdown + Vue 组件。

## 代码块增强

```python
print("Hello VitePress")                              # Python 代码

echo "Hello VitePress"                                # Bash 代码

提示框¶

::: info 信息这是信息提示框。 :::

::: tip 技巧这是技巧提示框。 :::

::: warning 警告这是警告提示框。 :::

::: danger 危险这是危险提示框。 :::

在 Markdown 中使用 Vue¶

当前计数：{{ count }}

## 构建部署

```bash
npx vitepress build                                   # 构建（输出到 .vitepress/dist）
npx vitepress preview                                 # 预览构建结果

# 部署到 GitHub Pages
# 在 .github/workflows/deploy.yml 中配置 Actions

常见报错¶

报错	原因	解决
`Cannot find module 'vitepress'`	未安装	`npm install -D vitepress`
`404 in production`	base 路径错误	设置 `base: '/repo-name/'`
`Vue component error`	Vue 语法错误	检查 `<script setup>` 语法
`Dead links`	链接失效	构建时会自动检测并报告

速查表¶

# 常用命令
npx vitepress init                                    # 初始化项目
npx vitepress dev                                     # 开发预览
npx vitepress build                                   # 构建
npx vitepress preview                                 # 预览构建

# 三大文档框架选择
# VitePress  → Vue 项目，追求速度
# Docusaurus → React 项目，需要版本管理
# MkDocs     → Python 项目，Material 主题