rspress-docs-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspress Docs Generator

Rspress 文档生成器

Create and maintain Rspress documentation as part of normal project work. Prefer source-backed docs over generic prose: read the code, tests, examples, package metadata, and existing README before writing.

将创建和维护Rspress文档作为常规项目工作的一部分。优先基于源代码生成文档，而非通用描述：在撰写前先阅读代码、测试用例、示例、包元数据及现有README。

Use Cases

使用场景

Create a new Rspress v2 documentation site for a project that has no docs site yet.
Update an existing Rspress v2 docs site for a user-facing feature, API change, CLI change, or PR.
Detect Rspress v1 version markers before documentation work and hand migration to the dedicated
```
rspress-v2-upgrade
```
skill.
Integrate Rspress documentation into an Rslib package or workspace while preserving the repository's package manager and scripts.

为尚无文档站点的项目创建新的Rspress v2文档站点。
针对面向用户的功能、API变更、CLI变更或PR，更新现有的Rspress v2文档站点。
在开展文档工作前检测Rspress v1版本标记，并将迁移工作转交至专属的
```
rspress-v2-upgrade
```
技能处理。
在保留仓库包管理器和脚本的前提下，将Rspress文档集成到Rslib包或工作区中。

Workflow

工作流程

Inspect the project
- Locate package files, source entry points, examples, tests, changelogs, and README files.
- Search for Rspress config files:
```
rspress.config.ts
```
  ,
```
.js
```
  ,
```
.mjs
```
  , or
```
.cjs
```
  .
- Inspect dependencies for Rspress version markers:
```
@rspress/core
```
  version, legacy
```
rspress
```
  package or
```
rspress/*
```
  imports, and
```
@rspress/plugin-*
```
  .
- Detect the package manager and workspace setup from lock files (
```
pnpm-lock.yaml
```
  ,
```
yarn.lock
```
  ,
```
package-lock.json
```
  ,
```
bun.lock
```
  ,
```
bun.lockb
```
  ) and
```
pnpm-workspace.yaml
```
  .
- If a config exists, resolve the docs root from its
```
root
```
  option. When
```
root
```
  is absent, inspect package scripts, CI commands, and documented commands for Rspress CLI positional roots such as
```
rspress dev site
```
  ,
```
rspress build site
```
  , or
```
rspress preview site
```
  ; use that argument before falling back to Rspress's default
```
docs/
```
  directory relative to the config file's project cwd. If no config exists, check common roots such as
```
docs/
```
  ,
```
doc/
```
  ,
```
website/
```
  , and
```
site/
```
  .
Choose the correct path
- If no Rspress docs site exists, follow Create New Docs.
- If a Rspress docs site exists but appears to be v1, follow Rspress Version Guard before editing docs.
- If a Rspress v2 docs site exists, follow Maintain Docs For PRs.
Validate before finishing
- Run the docs build from the Rspress project directory or through the repo's root script.
- The build must pass as the primary success criterion.
- Fix broken links, missing navigation entries, invalid frontmatter, and failed MDX imports before reporting completion.

检查项目
- 定位包文件、源代码入口、示例、测试用例、变更日志及README文件。
- 查找Rspress配置文件：
```
rspress.config.ts
```
  、
```
.js
```
  、
```
.mjs
```
  或
```
.cjs
```
  。
- 检查依赖中的Rspress版本标记：
```
@rspress/core
```
  版本、旧版
```
rspress
```
  包或
```
rspress/*
```
  导入，以及
```
@rspress/plugin-*
```
  。
- 从锁文件（
```
pnpm-lock.yaml
```
  、
```
yarn.lock
```
  、
```
package-lock.json
```
  、
```
bun.lock
```
  、
```
bun.lockb
```
  ）和
```
pnpm-workspace.yaml
```
  中检测包管理器和工作区设置。
- 若配置文件存在，从其
```
root
```
  选项解析文档根目录。当
```
root
```
  选项缺失时，检查包脚本、CI命令及已记录的Rspress CLI命令中的位置根目录，如
```
rspress dev site
```
  、
```
rspress build site
```
  或
```
rspress preview site
```
  ；优先使用该参数，若未找到则回退到Rspress默认的、相对于配置文件项目工作目录的
```
docs/
```
  目录。若不存在配置文件，检查常见根目录如
```
docs/
```
  、
```
doc/
```
  、
```
website/
```
  和
```
site/
```
  。
选择正确路径
- 若不存在Rspress文档站点，请遵循创建新文档流程。
- 若存在Rspress文档站点但版本为v1，请先遵循Rspress版本防护流程，再编辑文档。
- 若存在Rspress v2文档站点，请遵循为PR维护文档流程。
完成前验证
- 从Rspress项目目录或通过仓库根目录脚本运行文档构建。
- 构建必须成功是首要的验收标准。
- 在报告完成前，修复损坏的链接、缺失的导航条目、无效的前置元数据及失败的MDX导入。

Code Examples

代码示例

Use the repository's package manager when creating or validating docs:

bash

undefined

创建或验证文档时，请使用仓库的包管理器：

bash

undefined

Create a new Rspress docs site with the detected package manager.

使用检测到的包管理器创建新的Rspress文档站点。

Replace pnpm with npm, yarn, or bun when that is the repo package manager.

若仓库使用的是npm、yarn或bun，请替换pnpm。

pnpm create rspress@latest

Validate from the docs project after replacing starter content.

替换初始内容后，从文档项目验证构建。

pnpm run build


When maintaining docs for a PR, inspect the changed source first, then update the matching docs page and navigation:

```text
src/formatBytes.ts -> website/docs/api/formatBytes.mdx -> website/docs/api/_meta.json

pnpm run build


为PR维护文档时，请先检查变更的源代码，再更新对应的文档页面和导航：

```text
src/formatBytes.ts -> website/docs/api/formatBytes.mdx -> website/docs/api/_meta.json

Reference

参考资料

Documentation structure conventions — how
```
_nav.json
```
and
```
_meta.json
```
work, with concrete examples for Guide/API sites, grouped sections, and i18n layouts.
Create New Docs — scaffold a Rspress v2 docs site from an undocumented project.
Maintain Docs For PRs — update an existing Rspress v2 docs site for feature work.
Rspress Version Guard — detect v1 sites, avoid stale v1 scaffolds, and hand full migration to
```
rspress-v2-upgrade
```
.

文档结构规范 — 介绍
```
_nav.json
```
和
```
_meta.json
```
的工作方式，包含指南/API站点、分组章节及国际化布局的具体示例。
创建新文档 — 为无文档的项目搭建Rspress v2文档站点。
为PR维护文档 — 针对功能开发更新现有的Rspress v2文档站点。
Rspress版本防护 — 检测v1站点，避免使用过时的v1脚手架，并将完整迁移工作转交至
```
rspress-v2-upgrade
```
技能。