VitePress 是一个基于 Vite 和 Vue 3 的静态网站生成器,特别适用于构建文档网站。它提供了快速的开发体验、即时热更新以及优秀的性能。本文将详细介绍如何安装和配置 VitePress,并通过实例代码帮助你快速上手。
一、安装前准备
在开始之前,请确保你已经安装了以下工具:
- Node.js 版本 18 或更高。
- 终端 用于访问 VitePress 的命令行界面(CLI)。
- 文本编辑器 支持 Markdown 语法,推荐使用 VSCode,并安装官方 Vue 扩展。
二、安装 VitePress
VitePress 可以单独使用,也可以安装到现有项目中。无论哪种情况,你都可以通过以下包管理工具进行安装:
使用 npm:
$ npm add -D vitepress
使用 pnpm:
$ pnpm add -D vitepress
使用 yarn:
$ yarn add -D vitepress
使用 bun:
$ bun add -D vitepress
注意:VitePress 是一个 ESM(ECMAScript Module)包,不要使用 require()
来导入它。确保你的 package.json
中包含 "type": "module"
,或者将相关文件的扩展名更改为 .mjs
或 .mts
。
三、初始化项目
VitePress 提供了一个命令行设置向导,帮助你快速搭建基本项目。安装完成后,运行以下命令启动向导:
使用 npm:
$ npx vitepress init
使用 pnpm:
$ pnpm vitepress init
使用 yarn:
$ yarn vitepress init
使用 bun:
$ bun vitepress init
向导会询问你几个问题,例如配置文件的位置、网站标题、描述以及主题选择。根据你的需求进行选择即可。
四、项目结构
假设你选择将 VitePress 项目架构在 ./docs
目录下,生成的文件结构应如下所示:
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.json
docs
目录是 VitePress 站点的项目根目录,.vitepress
目录包含配置文件、开发服务器缓存、构建输出以及可选的主题定制代码。
五、配置文件
配置文件 .vitepress/config.js
允许你自定义 VitePress 站点的各个方面。最基本的配置选项包括站点的标题和描述:
// .vitepress/config.js
export default {
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// 主题级选项
}
}
你可以在 themeConfig
选项中配置主题的特定行为。有关所有配置选项的详细信息,请参阅配置引用。
六、源文件
.vitepress
目录之外的 Markdown 文件被视为源文件。VitePress 使用基于文件的路由:每个 .md
文件都会被编译成具有相同路径的相应 .html
文件。例如,index.md
将被编译为 index.html
,并可以通过 VitePress 站点的根路径 /
访问。
七、启动开发服务器
如果允许设置向导修改你的 package.json
,它会注入以下 npm 脚本:
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}
使用以下命令启动本地开发服务器:
$ npm run docs:dev
或者,你也可以直接调用 VitePress:
$ npx vitepress dev docs
开发服务器应运行在 http://localhost:5173
。在浏览器中访问该 URL,即可查看你的新站点。
八、下一步
- 路由指南:了解 Markdown 文件如何映射到生成的 HTML。
- 写作指南:学习如何编写 Markdown 内容和使用 Vue 组件。
- 默认主题配置:探索默认文档主题提供的功能。
- 自定义主题:进一步定制你的站点外观。
- 部署指南:将你的文档网站部署到线上。
通过以上步骤,你已经成功安装并配置了 VitePress。现在,你可以开始撰写文档,并利用 VitePress 提供的强大功能,轻松搭建现代、高效的文档网站。