跳至内容

入门

在线试用

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

安装

先决条件

  • Node.js 版本 18 或更高版本。
  • 用于通过其命令行界面 (CLI) 访问 VitePress 的终端。
  • 支持 Markdown 语法的文本编辑器。

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

sh
$ npm add -D vitepress
sh
$ pnpm add -D vitepress
sh
$ yarn add -D vitepress
sh
$ bun 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",或者将相关文件的扩展名(如 .vitepress/config.js)更改为 .mjs/.mts。有关更多详细信息,请参阅 Vite 的故障排除指南。此外,在异步 CJS 上下文中,您可以使用 await import('vitepress') 代替。

设置向导

VitePress 附带一个命令行设置向导,它将帮助您构建一个基本项目。安装后,通过运行以下命令启动向导

sh
$ npx vitepress init
sh
$ pnpm vitepress init
sh
$ yarn vitepress init
sh
$ 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 站点的各个方面,最基本的选择是站点的标题和描述

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
sh
$ bun run docs:dev

除了 npm 脚本,您还可以使用以下命令直接调用 VitePress

sh
$ npx vitepress dev docs
sh
$ pnpm vitepress dev docs
sh
$ yarn vitepress dev docs
sh
$ bun vitepress dev docs

有关更多命令行用法的文档,请参阅 CLI 参考

开发服务器应该在 https://127.0.0.1:5173 上运行。在浏览器中访问该 URL,即可看到您的新站点!

下一步?

  • 要更好地了解 Markdown 文件如何映射到生成的 HTML,请继续访问 路由指南

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

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

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

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