Skip to content
当前页导航

入门

在线尝试

您可以直接在浏览器中在StackBlitz上尝试VitePress。

安装

先决条件

  • Node.js 版本 18 或更高版本。
  • 用于通过命令行界面 (CLI) 访问 VitePress 的终端。
  • 具有 Markdown 语法支持的文本编辑器。
  • 推荐使用 VSCode 以及官方 Vue 扩展

VitePress 可以单独使用,也可以安装到现有项目中。在这两种情况下,您都可以使用以下命令安装它:

sh
$ npm install -D vitepress
sh
$ pnpm add -D vitepress@latest
sh
$ yarn add -D vitepress
收到了缺少对等依赖的警告?

如果使用 PNPM,您会注意到 @docsearch/js. 缺少对等警告。这并不妨碍 VitePress 工作。如果您希望抑制此警告,请将以下内容添加到您的package.json:

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 附带一个命令行设置向导,可帮助您构建基本项目。安装后,通过运行以下命令启动向导:

sh
$ npx vitepress init
sh
$ pnpm dlx vitepress init

您将收到几个简单的问题:

vitepress init screenshot

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 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的保留位置。

TIP

默认情况下,VitePress 将其开发服务器缓存存储在.vitepress/cache中,并将生产构建输出存储在.vitepress/dist中。如果使用 Git,您应该将它们添加到.gitignore文件中。这些位置也可以配置

配置文件

配置文件(.vitepress/config.js)允许您自定义 VitePress 站点的各个方面,最基本的选项是站点的标题和描述:

js
// .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 中:

json
{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev 脚本将启动本地开发服务器并进行即时热更新。使用以下命令运行它:

sh
$ npm run docs:dev
sh
$ pnpm run docs:dev
sh
$ yarn docs:dev

除了 npm 脚本之外,您还可以直接调用 VitePress:

sh
$ npx vitepress dev docs
sh
$ pnpm exec vitepress dev docs

更多命令行用法记录在 CLI 参考 中。

开发服务器应该在http://localhost:5173上运行。在浏览器中访问 URL 以查看正在运行的新网站!

下一步是什么?

  • 为了更好地理解 Markdown 文件如何映射到生成的 HTML,请继续阅读 路由指南

  • 要了解有关可以在页面上执行的操作的更多信息,例如编写 Markdown 内容或使用 Vue 组件,请参阅指南的"编写" 部分。一个很好的起点是了解 Markdown 扩展

  • 要探索默认文档主题提供的功能,请查看默认主题配置参考

  • 如果您想进一步自定义站点的外观,请探索如何扩展默认主题构建自定义主题

  • 一旦您的文档站点成型,请务必阅读部署指南

本文档由全栈行动派(qzxdp.cn)翻译并整理