快速开始 ​

在线尝试 ​

可以直接在 StackBlitz 上进行在线尝试。

安装 ​

前置知识 ​

• Node.js 16 及以上版本。
• 通过命令行界面 (CLI) 访问 VitePress 的终端。
• 支持 Markdown 语法的编辑器。
  • 推荐 VSCode 及其官方 Vue 扩展。

VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：

$ npm install -D vitepress

$ npm install -D vitepress

$ pnpm add -D vitepress

$ pnpm add -D vitepress

$ yarn add -D vitepress

$ yarn add -D vitepress

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search"
    ]
  }
}

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search"
    ]
  }
}

安装向导 ​

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

$ npx vitepress init

$ npx vitepress init

$ pnpm exec vitepress init

$ pnpm exec vitepress init

你将需要回答几个简单的问题：

文件结构 ​

如果你正在构建一个独立的 VitePress 站点，你可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。

假设你选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs 目录作为 VitePress 站点的项目根目录。.vitepress 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。

配置文件 ​

配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

// .vitepress/config.js
export default {
  // site-level options
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // theme-level options
  }
}

// .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"
  },
  ...
}

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

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

$ npm run docs:dev

$ npm run docs:dev

$ pnpm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ yarn docs:dev

除了 npm 脚本，还可以直接调用 VitePress：

$ npx vitepress dev docs

$ npx vitepress dev docs

$ pnpm exec vitepress dev docs

$ pnpm exec vitepress dev docs

更多的命令行用法请参见 CLI 参考。

开发服务应该会运行在 http://localhost:5173上。在浏览器中访问 URL 以查看新站点的运行情况吧！

下一步 ​

• 想要进一步了解 Markdown 文件是怎么映射到对应的 HTML，请继续阅读路由指南。

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

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

• 如果想进一步自定义站点的外观，参见扩展默认主题或者构建自定义主题。

• 文档成形以后，务必阅读部署指南。