入门
在线试用
您可以在 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.json
docs
目录被视为 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://127.0.0.1:5173
上运行。在浏览器中访问该 URL,即可看到您的新站点!