快速上手

本节将帮助你从头开始搭建一个简单的 VitePress 文档站点。

配置部署

先决条件

Node.js 版本 18 或更高版本。
用于通过其命令行界面（CLI）访问 VitePress 的终端。
建议使用 VSCode 以及 Vue 官方扩展。 VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，您都可以使用以下命令进行安装：

pnpm add -D vitepress

TIP

VitePress 是一个仅限 ESM 的软件包。不要用于 require () 导入它，并确保离您最近的 package.json 包含 "type": "module" ，或更改相关文件的文件扩展名，例如 .vitepress/config.js .mjs / .mts 。有关更多详细信息，请参阅 Vite 官方故障排除指南。此外，在异步 CJS 上下文中，您可以改用 await import ('vitepress') 。

安装向导

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

pnpm 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
└

文件结构

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

假设您选择在中搭建 VitePress 项目的脚手架 ./docs ，生成的文件结构应如下所示：

TIP

默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress/cache .vitepress/dist 中，并将生产构建输出存储在 .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 使用基于文件的路由：每个 .md 文件被编译成具有相同路径的相应 .html 文件。例如，将被编译成 index.html ， index.md 并且可以在生成的 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 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

pnpm run docs:dev

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

pnpm exec vitepress dev docs

CLI 参考中记录了更多命令行用法。开发服务器应在 http://localhost:5173 上运行。访问浏览器中的 URL，查看新网站的运行情况。如需指定端口，需修改 package.json 文件，添加 --port 端口号

json

"docs:dev": "vitepress dev docs --port 5173",

快速上手 ​

配置部署 ​

先决条件 ​

安装向导 ​

文件结构 ​

配置文件 ​

源文件 ​

启动并运行 ​

官方资料 ​