rspress-docs-generator

Rspress 文档生成器

将 Rspress 文档的创建与维护纳入常规项目工作。优先编写有源码依据的文档，而非泛泛而谈：在撰写前，先阅读代码、测试、示例、包元数据和现有 README。

使用场景

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

工作流程

1. 检查项目

   • 查找包文件、源码入口、示例、测试、变更日志和 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；优先使用该参数，然后再回退到相对于配置文件所在项目 cwd 的 Rspress 默认 docs/ 目录。如果不存在配置文件，请检查 docs/、doc/、website/ 和 site/ 等常见根目录。

2. 选择正确的路径

   • 如果不存在 Rspress 文档站点，请遵循创建新文档。
   • 如果存在 Rspress 文档站点，但看起来是 v1 版本，请在编辑文档前遵循 Rspress 版本检查。
   • 如果存在 Rspress v2 文档站点，请遵循为 PR 维护文档。

3. 完成前进行验证

   • 在 Rspress 项目目录中运行文档构建，或通过仓库根脚本运行。
   • 构建必须通过，这是首要的成功标准。
   • 在报告完成前，修复失效链接、缺失的导航条目、无效的 frontmatter 和失败的 MDX 导入。

代码示例

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

# Create a new Rspress docs site with the detected package manager.
# Replace pnpm with npm, yarn, or bun when that is the repo package manager.
pnpm create rspress@latest

# Validate from the docs project after replacing starter content.
pnpm run build

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

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

参考

• 文档结构约定 — 介绍 _nav.json 和 _meta.json 的工作方式，并提供指南/API 站点、分组章节和 i18n 布局的具体示例。
• 创建新文档 — 为尚无文档的项目搭建 Rspress v2 文档站点。
• 为 PR 维护文档 — 为功能开发更新现有的 Rspress v2 文档站点。
• Rspress 版本检查 — 检测 v1 站点，避免使用过时的 v1 脚手架，并将完整迁移交由 rspress-v2-upgrade 处理。