入门
在线试用
您可以在 StackBlitz 上直接在浏览器中试用 VitePress。
安装
先决条件
VitePress 可以独立使用，也可以安装到现有项目中。在这两种情况下，您都可以使用以下命令安装它
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ bun add -D vitepress缺少对等依赖项警告？
如果使用 PNPM，您会注意到 @docsearch/js 的缺少对等依赖项警告。这不会阻止 VitePress 工作。如果您想抑制此警告，请将以下内容添加到您的 package.json 中
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}注意
VitePress 是一个仅限 ESM 的包。不要使用 require() 导入它，并确保您最近的 package.json 包含 "type": "module"，或者将相关文件的扩展名（如 .vitepress/config.js）更改为 .mjs/.mts。有关更多详细信息，请参阅 Vite 的故障排除指南。此外，在异步 CJS 上下文中，您可以使用 await import('vitepress') 代替。
设置向导
VitePress 附带一个命令行设置向导，它将帮助您构建一个基本项目。安装后，通过运行以下命令启动向导
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress init您将看到一些简单的提示
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└Vue 作为对等依赖项
如果您打算执行使用 Vue 组件或 API 的自定义操作，您还应该显式地将 vue 安装为依赖项。
文件结构
如果您正在构建一个独立的 VitePress 站点，您可以在当前目录 (./) 中构建站点。但是，如果您正在将 VitePress 安装到现有项目中，与其他源代码并存，建议在嵌套目录（例如 ./docs）中构建站点，以便它与项目的其余部分分开。
假设您选择在 ./docs 中构建 VitePress 项目，生成的目录结构应如下所示
.
├─ 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) 允许您自定义 VitePress 站点的各个方面，最基本的选择是站点的标题和描述
// .vitepress/config.js
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、重写路径和动态生成页面的功能。这些将在 路由指南 中介绍。
启动并运行
如果您在设置过程中允许该工具这样做，它还应该将以下 npm 脚本注入到您的 package.json 中
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}docs:dev 脚本将启动一个带有即时热更新的本地开发服务器。使用以下命令运行它
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:dev除了 npm 脚本，您还可以使用以下命令直接调用 VitePress
$ npx vitepress dev docs$ pnpm vitepress dev docs$ yarn vitepress dev docs$ bun vitepress dev docs有关更多命令行用法的文档，请参阅 CLI 参考。
开发服务器应该在 https://:5173 上运行。在浏览器中访问该 URL，即可看到您的新站点！