VitePress 入门指南：从零开始构建文档网站-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00211/article/details/148377936

VitePress 入门指南：从零开始构建文档网站

VitePress 是一个基于 Vite 和 Vue 的静态站点生成器，专为构建高性能的技术文档而设计。它继承了 Vue 官方文档的优秀特性，同时提供了更快的构建速度和更现代化的开发体验。

如果你只是想快速体验 VitePress 的功能，可以在浏览器中直接尝试，无需本地安装。这种方式适合初次接触 VitePress 的用户快速了解其基本功能。

在开始使用 VitePress 前，请确保你的开发环境满足以下要求：

VitePress 既可以作为独立项目使用，也可以集成到现有项目中。以下是使用不同包管理器的安装命令：

# npm
npm add -D vitepress

# pnpm
pnpm add -D vitepress

# yarn
yarn add -D vitepress

# bun
bun add -D vitepress

如果你使用 PNPM 安装时遇到关于 @docsearch/js 的警告，可以通过在 package.json 中添加以下配置来忽略这些警告：

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

VitePress 是一个纯 ESM 模块，使用时需要注意：

VitePress 提供了便捷的命令行向导来初始化项目。安装完成后，运行以下命令启动向导：

# npm
npx vitepress init

# pnpm
pnpm vitepress init

# yarn
yarn vitepress init

# bun
bun vitepress init

初始化过程中，你需要回答几个简单的问题，包括项目名称、描述、主题等。如果你计划使用 Vue 组件或 API 进行自定义开发，记得将 Vue 安装为 peer dependency。

假设你将项目初始化在 ./docs 目录下，典型的 VitePress 项目结构如下：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

.vitepress 目录：存放配置文件、开发服务器缓存和构建输出
- config.js：主配置文件
- cache：开发服务器缓存（建议加入.gitignore）
- dist：生产构建输出（建议加入.gitignore）
Markdown 文件：位于 .vitepress 目录外的 .md 文件是内容源文件，会按照文件路径转换为对应的 HTML 页面。

.vitepress/config.js 是 VitePress 的核心配置文件，允许你自定义网站的各个方面。最基本的配置包括网站标题和描述：

export default {
  // 网站级配置
  title: '我的文档网站',
  description: '这是我的第一个 VitePress 网站',
  
  themeConfig: {
    // 主题级配置
  }
}

初始化完成后，你的 package.json 中会自动添加以下脚本：

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

要启动开发服务器，运行：

npm run docs:dev

开发服务器默认运行在 http://localhost:5173，支持热重载，任何文件更改都会自动刷新浏览器。

VitePress 结合了现代前端工具链的优势，为技术文档编写提供了极佳的开发体验。通过本指南，你应该已经掌握了 VitePress 的基本使用方法，接下来可以深入探索其更多高级功能。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考