> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# 快速开始


For your Agent

一键创建 Rspress 项目

复制这段 Prompt 发送给你的 AI Agent，它会自动帮你搭建一个全新的 Rspress 站点。

复制 Prompt

按照官方快速开始指南 https://rspress.rs/guide/start/getting-started.md
创建一个 Rspress 项目。

1. 使用 `create rspress@latest` 初始化项目。
2. 安装依赖。
3. 启动开发服务器。

## 环境准备

Rspress 支持使用 [Node.js](https://nodejs.org/)、[Deno](https://deno.com/) 或 [Bun](https://bun.sh/) 作为 JavaScript 运行时。

你可以参考以下安装指南，选择其中一种运行时：

- [安装 Node.js](https://nodejs.org/en/download)
- [安装 Bun](https://bun.com/docs/installation)
- [安装 Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip 版本要求

Rspress 需要 Node.js 版本 20.19+, 22.12+。

:::

## 创建 Rspress 项目

使用 [`create-rspress`](https://www.npmjs.com/package/create-rspress) 来创建一个 Rspress 项目，运行以下命令：


```sh [npm]
npm create rspress@latest
```

```sh [yarn]
yarn create rspress
```

```sh [pnpm]
pnpm create rspress@latest
```

```sh [bun]
bun create rspress@latest
```

```sh [deno]
deno init --npm rspress@latest
```

按照提示一步步操作即可。在创建过程中，你可以输入项目名称或路径、选择是否启用 i18n、是否创建用于自定义主题的 `theme` 目录，以及是否添加可选工具或 Skills。

脚手架默认会在生成的项目中初始化 Git 仓库。如需跳过 Git 初始化，请在创建命令中添加 `--no-git`。

项目创建完成后，你可以执行以下步骤：

- 执行 `npm install`（或其他包管理器的 install 命令）安装 npm 依赖。
- 执行 `npm run dev` 启动开发服务器。

开发服务启动后会在终端输出本地访问地址，打开该地址即可查看生成的文档站点。

### 模板

Rspress 提供以下内置模板：

| 模板            | 说明                          |
| ------------- | --------------------------- |
| `basic`       | 创建一个使用默认主题的最小 Rspress 文档站点。 |
| `basic-theme` | 创建一个带有 `theme` 目录的单语言文档站点。  |
| `i18n`        | 创建一个包含英文和中文内容的多语言文档站点。      |
| `i18n-theme`  | 创建一个带有 `theme` 目录的多语言文档站点。  |

### 可选工具

`create-rspress` 能够帮助你设置以下常用工具，你可以使用上下箭头和空格进行选择。如果你不需要这些工具，可以直接按回车跳过。

| 工具         | 用途                   |
| ---------- | -------------------- |
| `rslint`   | 添加 Rslint，用于代码检查。    |
| `eslint`   | 添加 ESLint，用于代码检查。    |
| `prettier` | 添加 Prettier，用于格式化。   |
| `biome`    | 添加 Biome，用于代码检查和格式化。 |

### 可选 Skills

如果你计划使用 AI Agent 维护文档站点，可以在创建项目时选择可选的 Agent Skills。CLI 会在项目中生成 `.agents/skills` 目录，并把选中的 Skills 放到该目录下。

对于大多数文档站点，推荐选择：

- [rspress-docs-generator](https://github.com/rstackjs/agent-skills#rspress-docs-generator)：帮助 AI Agent 创建和维护 Rspress 文档站点，尤其适合在 monorepo 中维护一个独立 Rspress 项目作为文档站的场景。
- [rspress-best-practices](https://github.com/rstackjs/agent-skills#rspress-best-practices)：为 AI Agent 提供 Rspress 项目结构、配置、MDX、主题和部署等最佳实践。
- [rspress-description-generator](https://github.com/rstackjs/agent-skills#rspress-description-generator)：帮助 AI Agent 编写和维护页面 description，用于 SEO、搜索和 AI 可读产物。

如果你选择了 `basic-theme` 或 `i18n-theme` 模板，以下 Skill 会被默认勾选：

- [rspress-custom-theme](https://github.com/rstackjs/agent-skills#rspress-custom-theme)：让你的 AI Agent 为你定制 Rspress 主题，例如 CSS 变量、Layout slots 和主题组件覆盖。

这些 Skills 不会影响 Rspress 站点的运行时行为，只是为 AI Agent 编辑和维护项目提供本地指导。如果你不使用 AI Agent，可以取消勾选，或按回车跳过这个选项。

关于 Agent Skills 和其他 AI 相关能力的更多介绍，可参考 [AI](https://rspress.rs/zh/guide/start/ai.md)。

### 当前目录

如果你需要在当前目录下创建项目，可以将 target folder 设置为 `.`：

```bash
◆  Create Rspress Project

◇  Project name or path
│  .
```

如果当前目录不为空，CLI 会询问是否继续并覆盖文件。

### 非交互模式

[`create-rspress`](https://www.npmjs.com/package/create-rspress) 支持通过命令行选项进入非交互模式。使用该模式可以跳过所有提示，直接创建项目，适合脚本、CI 以及 coding agents 等自动化场景。

例如，以下命令将在 `my-docs` 目录中创建一个 Rspress 项目：

```bash
npx -y create-rspress@latest --dir my-docs --template basic-theme
```

使用缩写：

```bash
npx -y create-rspress@latest -d my-docs -t basic-theme
```

指定多个 tools：

```bash
npx -y create-rspress@latest -d my-docs -t basic-theme --tools rslint,prettier
```

创建多语言模板：

```bash
npx -y create-rspress@latest -d my-docs -t i18n
```

创建带 `theme` 目录的多语言模板：

```bash
npx -y create-rspress@latest -d my-docs -t i18n-theme
```

安装可选的 Agent Skill：

```bash
npx -y create-rspress@latest -d my-docs -t basic-theme --skill rspress-docs-generator,rspress-best-practices
```

`create-rspress` 完整的 CLI 选项如下：

```bash
Usage: create-rspress [dir] [options]

Options:

  -h, --help                display help for command
  -d, --dir <dir>           create project in specified directory
  -t, --template <tpl>      specify the template to use
  --no-git                  skip Git repository initialization
  --tools <tool>            add additional tools, comma separated
  --skill <skill>           add optional skills, comma separated
  --override                override files in target directory
  --packageName <name>      specify the package name
  --template-version <ver>  specify the npm template version

Available templates:
  basic, basic-theme, i18n, i18n-theme

Optional tools:
  eslint, rslint, biome, prettier

Optional skills:
  rspress-docs-generator, rspress-best-practices, rspress-custom-theme, rspress-description-generator
```

## 手动创建

如果你想在已有项目中添加 Rspress，或希望自己创建最小文件，可以先创建一个目录：

```bash
mkdir rspress-app && cd rspress-app
```

初始化 `package.json`：

```bash
npm init -y
```

安装 Rspress：


```sh [npm]
npm install @rspress/core -D
```

```sh [yarn]
yarn add @rspress/core -D
```

```sh [pnpm]
pnpm add @rspress/core -D
```

```sh [bun]
bun add @rspress/core -D
```

```sh [deno]
deno add npm:@rspress/core -D
```

创建第一篇文档：

```bash
mkdir docs && echo '# Hello world' > docs/index.md
```

在 `package.json` 中添加以下脚本：

```json
{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  }
}
```

创建配置文件：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  // 文档根目录
  root: 'docs',
});
```

创建 `tsconfig.json`：

```json
{
  "compilerOptions": {
    "lib": ["DOM", "ES2023"],
    "jsx": "react-jsx",
    "target": "ES2023",
    "noEmit": true,
    "skipLibCheck": true,
    "useDefineForClassFields": true,

    /* modules */
    "module": "ESNext",
    "moduleDetection": "force",
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noUncheckedSideEffectImports": true,
    "isolatedModules": true,

    /* type checking */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}
```

## 启动 Dev server

通过如下命令启动本地开发服务：

```bash
npm run dev
```

:::tip 提示

对于 dev 命令，你可以通过 `--port` 或 `--host` 参数来指定开发服务的端口号或 host，例如 `rspress dev --port 8080 --host 0.0.0.0`。

:::

## 生产环境构建

通过如下命令构建生产环境的产物：

```bash
npm run build
```

默认情况下，Rspress 会把生产环境产物输出到 `doc_build` 目录。

## 本地预览产物

通过如下命令启动本地预览服务：

```bash
npm run preview
```

预览服务会基于 `doc_build` 中的生产环境产物启动。

## 下一步

- 阅读 [基础功能](https://rspress.rs/zh/guide/basic/conventional-route.md)，了解路由、首页、静态资源、部署等常见文档站点能力。
- 阅读 [使用 MDX](https://rspress.rs/zh/guide/use-mdx/components.md)，了解如何编写 MDX，并在文档中使用组件。
- 阅读 [配置](https://rspress.rs/zh/api/config/config-basic.md)，了解所有 Rspress 配置项。