VitePress 文档

快速导航

• 简介
  • 核心特性
  • 适用场景
• 快速开始
  • 环境要求
  • 安装步骤
• 项目结构
• 基础配置
  • 站点配置
  • Frontmatter
• Markdown 增强
  • 代码块
  • 代码组
  • 提示容器
• 主题定制
  • 导航栏配置
  • 侧边栏配置
• 部署指南
  • 构建
  • 部署平台
• 进阶功能
  • 国际化
  • Algolia 搜索
  • PWA 支持

简介

VitePress 是一个基于 Vite 构建的静态站点生成器，专注于技术文档的编写和发布。作为 VuePress 的精神继承者，它采用了更现代的技术栈，提供极速的开发体验。

核心特性

• 极速响应: 基于 Vite 构建，提供极快的开发体验
• 简单易用: 约定优于配置，专注内容创作
• Markdown 增强: 丰富的扩展功能支持
• Vue 驱动: 支持在 Markdown 中使用 Vue 组件

适用场景

• 技术文档
• API 文档
• 组件库文档
• 个人博客
• 项目文档
• 团队知识库

快速开始

环境要求

• Node.js >= 16.0.0
• npm、yarn 或 pnpm（推荐）

安装步骤

1. 创建并进入项目目录

mkdir my-docs
cd my-docs

2. 初始化项目

npm init

3. 安装 VitePress

npm install -D vitepress

4. 创建文档

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

5. 配置 package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

项目结构

.
├── docs
│   ├── .vitepress
│   │   └── config.js    # 配置文件
│   ├── public          # 静态资源
│   └── index.md        # 首页
└── package.json

基础配置

站点配置

在 .vitepress/config.js 中配置：

export default {
  title: '站点标题',
  description: '站点描述',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: [...]
  }
}

Frontmatter

在 Markdown 文件顶部配置：

---
title: 页面标题
description: 页面描述
layout: home
---

Markdown 增强

VitePress 提供了丰富的 Markdown 增强特性：

代码块

支持语法高亮：

console.log('Hello VitePress!')

代码组

config.js

export default {
  // ...
}

config.ts

export default {
  // ...
}

提示容器

提示

这是一个提示

警告

这是一个警告

主题定制

导航栏配置

export default {
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ]
  }
}

侧边栏配置

export default {
  themeConfig: {
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '介绍', link: '/guide/introduction' },
          { text: '快速开始', link: '/guide/getting-started' }
        ]
      }
    ]
  }
}

部署指南

构建

npm run docs:build

部署平台

• GitHub Pages
• Netlify
• Vercel
• 自托管服务器

进阶功能

国际化

export default {
  locales: {
    '/': {
      lang: 'zh-CN',
      title: '中文站点'
    },
    '/en/': {
      lang: 'en-US',
      title: 'English Site'
    }
  }
}

Algolia 搜索

export default {
  themeConfig: {
    algolia: {
      appId: '...',
      apiKey: '...',
      indexName: '...'
    }
  }
}

PWA 支持

export default {
  head: [
    ['link', { rel: 'manifest', href: '/manifest.json' }],
    ['meta', { name: 'theme-color', content: '#3eaf7c' }]
  ],
  serviceWorker: true
}