快速开始
使用前你的电脑需要满足以下条件：
- 安装 node.js 并 >= 18
- 支持通过其命令行界面(bash、cmd 等)访问 VitePress
- 支持 Markdown 语法的文本编辑器（强烈推荐 vscode）
安装
VitePress 可以单独使用，也可以安装到现有项目中。两者都可以使用以下命令安装它：
pnpm add -D vitepressnpm install -D vitepressyarn add -D vitepress缺少包的警告
如果使用 PNPM，可能会出现 @docsearch/js 缺少的警告。
这不会阻止 VitePress 工作。如果您希望取消此警告，请将以下内容添加到您的 package.json：
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}注意
VitePress 是一个仅支持 ESM 的软件包。
不要使用 require() 来导入它，并确保您的 package.json 包含：
{
"type": "module"
}或者将相关文件的文件扩展名更改为 .mjs/.mts ，比如：.vitepress/config.js 。有关详细信息，请参阅 [Vite 的故障排除指南]。另外，在异步 CJS 上下文中，你可以使用 await import('vitepress')。
安装向导
VitePress 附带一个命令行设置向导，可帮助您搭建基本项目的基架。
[安装]后，通过运行以下命令启动向导：
pnpm dlx vitepress init
# pnpm exec vitepress init您会看到几个简单的问题：
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./
│
◇ Site title:
│ test Project
│
◇ Site description:
│ 测试站点描述
│
◇ Theme:
│ Default Theme + Customization
│
◇ Use TypeScript for config and theme files?
│ Yes
│
◇ Add VitePress npm scripts to package.json?
│ Yes
│
└ Done! Now run npm run docs:dev and start writing.
Tips:
- Since you've chosen to customize the theme, you should also explicitly install vue as a dev dependency.┌ 欢迎使用 VitePress!
│
◇ VitePress应该在哪里初始化配置？
│ ./
│
◇ 站点标题:
│ 测试站点
│
◇ 站点描述:
│ 测试站点描述
│
◇ 主题:
│ Default Theme + Customization
│
◇ 对配置文件和主题文件使用TypeScript?
│ Yes
│
◇ 将 VitePress 包添加到 npm 脚本文件 package.json?
│ Yes
│
└ 完成！现在运行 npm run docs:dev 并开始编写。
Tips:
- 既然您已经选择了自定义主题，那么您还应该明确地将vue作为开发依赖项安装。安装依赖
像上面我们选择了自定义主题，就应该显式安装 vue 作为项目依赖：
pnpm add -D vue项目结构
常见的 VitePress 项目结构有 2 种：
- 单独使用
- 安装到项目的
/docs目录中
.
├─ .vitepress
│ └─ config.js
├─ api-examples.md
├─ markdown-examples.md
├─ index.md
└─ package.json.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsondocs 目录被认为是 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 的配置文件、开发服务器缓存、构建输出和可选的主题自定义代码的保留位置。
提示
默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache 中，并将生产构建输出存储在 .vitepress/dist 中。
如果使用 Git，则应将它们添加到 .gitignore 文件中。当然这些位置也可以在配置文件里修改。
配置文件
配置文件（.vitepress/config.(js|ts|mts)）允许您自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：
// .vitepress/config.mts
export default {
// site-level options
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// theme-level options
},
};您还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的详细信息，请参阅[配置参考]。
源文件
.vitepress 目录外的 Markdown 文件被认为是源文件。
VitePress 使用基于文件的路由：每个 .md 文件被编译成具有相同路径的对应 .html 文件。
例如，index.md 将被编译为 index.html，并且可以在生成的 VitePress 站点的根路径 / 处访问。
VitePress 还提供了生成干净 URL、重写路径和动态生成页面的能力。这些将在 [路由指南] 中介绍。
启动并运行
如果按上面的步骤下来， package.json 的 script 选项已经加入：
{
...
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
},
...
}{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}# 使用 npm 脚本
pnpm docs:dev
# 直接调用 VitePress - 文档在 项目根目录
pnpm exec vitepress dev
# 直接调用 VitePress - 文档在 ./docs目录
pnpm exec vitepress dev docs# 使用 npm 脚本
pnpm docs:build
# 直接调用 VitePress - 文档在 项目根目录
pnpm exec vitepress build
# 直接调用 VitePress - 文档在 ./docs目录
pnpm exec vitepress build docs
# 生成后，通过运行以下命令在本地预览它
pnpm docs:preview更多命令行用法请参见 [CLI 参考]
开发服务器应该在 http://localhost:5173 运行。访问浏览器中的 URL，查看您的新网站的运行！