快速开始
在线试用
你可以直接在 StackBlitz 上在线试用 VitePress。
安装
前置条件
VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ bun add -D vitepress获得缺失的对等依赖警告？
如果使用 PNPM，你会注意到缺少对等依赖的警告。这不会阻止 VitePress 工作。如果你希望抑制这些警告，请将以下内容添加到你的 package.json：
"pnpmfile": {
"hooks": {
"readPackage": "pnpmfile.js"
}
}...并创建一个 pnpmfile.js：
function readPackage(pkg) {
if (pkg.name === 'vitepress') {
pkg.peerDependencies = {
...pkg.peerDependencies,
'@algolia/client-search': '*',
'@types/markdown-it': '*',
'search-insights': '*'
}
}
return pkg
}
module.exports = { readPackage }安装向导
VitePress 附带一个命令行安装向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bunx 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 + 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.TypeScript 作为依赖项
如果你打算使用 TypeScript 配置或主题自定义，请确保也安装 typescript 作为依赖项。
$ npm add -D typescript文件结构
如果你正在构建一个独立的 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 {
// 站点级选项
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// 主题级选项
}
}你还可以通过 themeConfig 选项配置默认主题的行为。有关所有可用选项的详细信息，请查阅配置参考。
源文件
.vitepress 目录之外的 Markdown 文件被视为源文件。
VitePress 使用基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。
VitePress 还提供了生成简洁 URL 的能力。有关详细信息，请参阅路由指南。
启动并运行
该工具还应该向你的 package.json 添加以下 npm 脚本：
{
...
"scripts": {
"docs:build": "vitepress build docs",
"docs:dev": "vitepress dev 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$ bunx vitepress dev docs命令行的更多用法记录在 CLI 参考中。
开发服务器应该运行在 http://localhost:5173。在浏览器中访问 URL 以查看你的新站点！