快速开始 ​

本节将帮助您从头开始构建一个基本的 VitePress 文档网站。

在线试用 ​

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

安装 ​

安装准备 ​

• Node.js 版本 16 或更高。
• 通过命令行界面可以访问Vitepress的终端。
• 支持Markdown语法的文本编辑器。
  • 推荐使用VSCode以及官方Vue扩展。

创建并进入一个新目录

$ mkdir vitepress-starter && cd vitepress-starter

VitePress可以单独使用，也可以安装到现有项目中。在这两种情况下，您都可以使用以下工具安装：（下面为项目添加 vitepress 和 vue 作为开发依赖项）

$ npm install -D vitepress vue

$ pnpm add -D vitepress vue

$ yarn add -D vitepress vue

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

安装向导 ​

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

$ npm install -g npx
$ npx 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站点的项目根目录。.vitepress目录是VitePress的配置文件、开发服务器缓存、构建输出和可选主题定制代码的保留位置。

配置文件 ​

配置文件（.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、重写路径和动态生成页面的能力。这些将在路由指南中介绍。

启动和运行 ​

如果您在安装过程中选择允许，则该工具还应该向package.json注入以下npm脚本，也可以手动向 package.json 中添加一些脚本

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

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

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

您也可以使用以下命令直接调用 VitePress，而不是 npm 脚本：

$ npx vitepress dev docs

$ pnpm exec vitepress dev docs

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

开发服务器将在 http://localhost:5173 运行，访问浏览器中的 URL 以查看您的新网站运行情况。

下一步是什么？ ​

• 要更好地了解Markdown 文件如何映射到生成的 HTML，请继续阅读路由指南。
• 要发现更多关于你可以在页面上做什么，比如写Markdown内容或使用Vue组件，请参考指南的“写作”部分。一个很好的起点是了解Markdown 扩展。
• 要探索默认文档主题提供的功能，请查看默认主题配置参考。
• 如果要进一步自定义网站的外观，请探索如何扩展默认主题或构建自定义主题。
• 文档站点形成后，请务必阅读部署指南。