diff --git a/README.md b/README.md index 27fafac..1609b4f 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,14 @@ Migrate tsc or tsup library projects to Rslib. ## Rspress Skills +### rspress-docs-generator + +```bash +npx skills add rstackjs/agent-skills --skill rspress-docs-generator +``` + +Generate or maintain Rspress documentation for a project. Use when creating a new Rspress v2 docs site from an undocumented project, adding docs for user-facing feature PRs, or migrating an existing Rspress v1 docs site before continuing documentation work. + ### rspress-best-practices ```bash diff --git a/skills-test/rspress-docs-generator/evals/evals.json b/skills-test/rspress-docs-generator/evals/evals.json new file mode 100644 index 0000000..e290b9a --- /dev/null +++ b/skills-test/rspress-docs-generator/evals/evals.json @@ -0,0 +1,48 @@ +{ + "skill_name": "rspress-docs-generator", + "fixture_root": "/Users/bytedance/Documents/codes/agent-skills/skills/rspress-docs-generator-workspace/fixtures", + "evals": [ + { + "id": 1, + "eval_name": "create-new-docs", + "fixture": "create-new-docs", + "prompt": "This repository is a small TypeScript utility package called `string-kit` with no documentation site. It lives at /Users/bytedance/Documents/codes/agent-skills/skills/rspress-docs-generator-workspace/fixtures/create-new-docs. The package exports `camelCase`, `kebabCase`, and `snakeCase` from `src/case.ts`, plus `truncate` and `ellipsis` from `src/truncate.ts`. The README explains basic usage and the package.json has a `test` script using vitest. Create a new Rspress v2 documentation site for this project. Choose an appropriate docs directory, scaffold with the correct package manager, write source-backed pages, configure navigation, and ensure the docs build passes.", + "expected_output": "A Rspress v2 docs site is scaffolded under a sensible directory (e.g. website/ or docs/), with real pages derived from the source, correct navigation, and a passing docs build. No placeholder starter content remains.", + "files": [], + "assertions": [ + "The docs site uses Rspress v2 (package.json contains @rspress/core ^2.x or rspress ^2.x, not v1)", + "A docs directory exists (e.g. website/docs/ or docs/) with an index/home page", + "Navigation files (_nav.json or _meta.json) are present and valid JSON", + "The generated docs mention the project's utilities (camelCase, kebabCase, snakeCase, truncate, ellipsis)", + "The docs build command exits with code 0" + ] + }, + { + "id": 2, + "eval_name": "maintain-docs-for-pr", + "fixture": "maintain-docs-pr", + "prompt": "This repository already has a Rspress v2 docs site under `website/`. It lives at /Users/bytedance/Documents/codes/agent-skills/skills/rspress-docs-generator-workspace/fixtures/maintain-docs-pr. A feature branch has been checked out that adds a new exported function `formatBytes(bytes: number, opts?: { decimals?: number }): string` in `src/formatBytes.ts`, along with tests. The PR title is 'feat: add formatBytes utility'. Update the Rspress documentation to cover this new feature, following the existing docs conventions. The docs build must still pass.", + "expected_output": "The docs site is updated with a new or existing page that documents formatBytes, including a usage example and type signature. Navigation is updated if needed and the docs build passes.", + "files": [], + "assertions": [ + "formatBytes is documented in at least one docs page", + "The formatBytes documentation includes a usage example", + "If a new page was added, navigation (_meta.json or _nav.json) is updated to include it", + "The docs build command exits with code 0" + ] + }, + { + "id": 3, + "eval_name": "migrate-rspress-v1", + "fixture": "migrate-rspress-v1", + "prompt": "This repository has an existing Rspress v1 documentation site under `site/`. It lives at /Users/bytedance/Documents/codes/agent-skills/skills/rspress-docs-generator-workspace/fixtures/migrate-rspress-v1. The site uses `@rspress/core` v1 and has a minimal config and docs. Migrate the site to Rspress v2 by following the official migration guide, update dependencies and config, and ensure the docs build passes on v2.", + "expected_output": "The docs site depends on Rspress v2 packages, the config and imports follow v2 conventions, and `rspress build` succeeds.", + "files": [], + "assertions": [ + "The docs site depends on Rspress v2 (package.json contains @rspress/core ^2.x or rspress ^2.x, not v1)", + "The rspress.config.ts imports and API usage follow v2 conventions", + "The docs build command exits with code 0" + ] + } + ] +} diff --git a/skills-test/rspress-docs-generator/report.md b/skills-test/rspress-docs-generator/report.md new file mode 100644 index 0000000..6e02b43 --- /dev/null +++ b/skills-test/rspress-docs-generator/report.md @@ -0,0 +1,49 @@ +# rspress-docs-generator - evaluation report + +**Date:** 2026-06-15 +**Model:** Not recorded in the raw run artifacts; timing artifacts only captured tokens and duration. +**Skill version:** `skills/rspress-docs-generator/SKILL.md` at `feat/rspress-generate-docs-eval` HEAD (`4efd2b6`) +**Iteration:** `skills/rspress-docs-generator-workspace/iteration-1` + +## Setup + +- **Eval definitions:** `skills-test/rspress-docs-generator/evals/evals.json` +- **Fixtures:** `skills/rspress-docs-generator-workspace/fixtures` +- **Run shape:** 3 evals, one `with_skill` run and one `without_skill` baseline per eval. +- **Grader:** assertion-based post-hoc checks in each run directory's `grading.json`. +- **Aggregate artifacts:** `skills/rspress-docs-generator-workspace/iteration-1/benchmark.json` and `benchmark.md`. + +## Aggregate Results + +| Config | Assertion pass rate | Mean per-eval pass rate | Mean tokens | Mean time | +| ------------- | ------------------: | ----------------------: | ----------: | --------: | +| with_skill | 12/12 (100.0%) | 100.0% | 27.2k | 192.2s | +| without_skill | 11/12 (91.7%) | 93.3% | 25.2k | 589.1s | + +The skill improved assertion pass rate by 8.3 percentage points on this run and cut mean wall time by 396.8s. It used about 2.0k more tokens on average. + +## Per-Eval Breakdown + +| Eval | Config | Passed | Total | Rate | Tokens | Time | +| -------------------- | ------------- | -----: | ----: | ---: | -----: | ------: | +| create-new-docs | with_skill | 5 | 5 | 100% | 24.2k | 172.9s | +| create-new-docs | without_skill | 4 | 5 | 80% | 29.0k | 1338.4s | +| maintain-docs-for-pr | with_skill | 4 | 4 | 100% | 36.8k | 244.0s | +| maintain-docs-for-pr | without_skill | 4 | 4 | 100% | 29.5k | 325.1s | +| migrate-rspress-v1 | with_skill | 3 | 3 | 100% | 20.6k | 159.8s | +| migrate-rspress-v1 | without_skill | 3 | 3 | 100% | 16.9k | 103.7s | + +## Findings + +- **create-new-docs:** The skill-guided run passed all checks. The baseline produced working docs but used `rspress@^1.0.0`, so it failed the Rspress v2 dependency assertion. This is the only failed assertion in the benchmark. +- **maintain-docs-for-pr:** Both runs passed. The eval confirms the task is achievable without the skill, so future iterations may need stricter assertions around matching existing Rspress conventions if this case should differentiate skill value. +- **migrate-rspress-v1:** Both runs passed. The baseline was faster and used fewer tokens on this small fixture, but the skill-guided run also completed the v2 migration correctly. + +## Raw Artifacts + +- `skills/rspress-docs-generator-workspace/iteration-1/create-new-docs/with_skill` +- `skills/rspress-docs-generator-workspace/iteration-1/create-new-docs/without_skill` +- `skills/rspress-docs-generator-workspace/iteration-1/maintain-docs-for-pr/with_skill` +- `skills/rspress-docs-generator-workspace/iteration-1/maintain-docs-for-pr/without_skill` +- `skills/rspress-docs-generator-workspace/iteration-1/migrate-rspress-v1/with_skill` +- `skills/rspress-docs-generator-workspace/iteration-1/migrate-rspress-v1/without_skill` diff --git a/skills/rspress-docs-generator/SKILL.md b/skills/rspress-docs-generator/SKILL.md new file mode 100644 index 0000000..629ea55 --- /dev/null +++ b/skills/rspress-docs-generator/SKILL.md @@ -0,0 +1,34 @@ +--- +name: rspress-docs-generator +description: Generate or maintain Rspress documentation for a project. Use whenever the user wants to create a new docs site from a project that has no documentation, automatically add docs for user-facing feature work or PRs, or migrate an existing Rspress v1 docs site to v2. Also use when the project uses Rslib and needs documentation integration. +--- + +# Rspress Docs Generator + +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. + +## Workflow + +1. **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`, `@rspress/core`, and `@rspress/plugin-*`. + - Detect the package manager and workspace setup from lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lockb`) and `pnpm-workspace.yaml`. + - If a config exists, resolve the docs root from its `root` option; otherwise check common roots such as `docs/`, `doc/`, `website/`, and `site/`. + +2. **Choose the correct path** + - If no Rspress docs site exists, follow [Create New Docs](references/create-new-docs.md). + - If a Rspress docs site exists and is v1, follow [Migrate Rspress v1](references/migrate-rspress-v1.md). + - If a Rspress v2 docs site exists, follow [Maintain Docs For PRs](references/maintain-docs-for-prs.md). + +3. **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. + +## Reference + +- [Documentation structure conventions](references/doc-structure-conventions.md) — how `_nav.json` and `_meta.json` work, with concrete examples for Guide/API sites, grouped sections, and i18n layouts. +- [Create New Docs](references/create-new-docs.md) — scaffold a Rspress v2 docs site from an undocumented project. +- [Maintain Docs For PRs](references/maintain-docs-for-prs.md) — update an existing Rspress v2 docs site for feature work. +- [Migrate Rspress v1](references/migrate-rspress-v1.md) — migrate an existing Rspress v1 docs site to v2. diff --git a/skills/rspress-docs-generator/references/create-new-docs.md b/skills/rspress-docs-generator/references/create-new-docs.md new file mode 100644 index 0000000..a2f9c8f --- /dev/null +++ b/skills/rspress-docs-generator/references/create-new-docs.md @@ -0,0 +1,73 @@ +# Create New Docs + +Use this path when the current project has no existing Rspress documentation site. + +1. **Understand the project from source** + - Read the root `README.md` and main `package.json`. + - Identify the project type: library, CLI tool, application, plugin, monorepo package, etc. + - Read public source entry points, exported types, examples, and representative tests to understand the user-facing surface. + - Determine the target audience and what to document: getting started, configuration, API reference, CLI commands, examples, migration notes, or plugin usage. + - Cross-check Rspress basics against the official docs when choosing structure or syntax: + - Quick start: + - Conventional route: + - Frontmatter: + +2. **Choose the docs site location** + - If the repository already has a conventional docs directory (`docs/`, `doc/`, `website/`, `site/`), prefer reusing it. + - Otherwise, propose a short list of options to the user, such as `website/`, `docs/`, or `site/`, and ask which to use. + - For monorepos, place the docs site so it can reference workspace packages without crossing too many directory boundaries. + +3. **Scaffold Rspress v2** + - See the official getting-started guide for the latest creation steps: + - + - Check the create package major before running the scaffold: + + ```bash + npm view create-rspress@latest version + ``` + + - If the version is `2.x`, scaffold with the package manager used by the repo: + + ```bash + # interactive (recommended for first-time setup) + npm create rspress@latest + + # or non-interactive, e.g. for CI/automation + npx -y create-rspress@latest my-docs --template basic-theme --tools rslint,prettier + ``` + + - If `latest` is not `2.x`, do not use a v1 scaffold. Use a current 2.x create package instead, such as `npm create rspress@2`, or pin a known 2.x version. + - Prefer the detected package manager for installs and scripts (`pnpm create rspress@latest`, `yarn create rspress@latest`, `bun create rspress@latest`, etc.). + - Pick a template that matches the project: + - `basic` — minimal site with the default theme. + - `basic-theme` — adds a `theme/` folder for customization. + - `i18n` — multilingual English/Chinese setup. + - `i18n-theme` — multilingual setup with a theme folder. + - If the project uses Rslib, follow the Rslib + Rspress integration guide instead of the generic scaffold: + - + +4. **After scaffolding** + - Install dependencies and verify the dev server starts: + + ```bash + cd + npm install + npm run dev + ``` + + - Rspress requires Node.js `^20.19.0 || >=22.12.0`. If the repo's Node version is older, surface this to the user before proceeding. + - Default build output goes to `doc_build/`. Keep it out of source control unless the repository already commits it. + +5. **Replace starter content** + - Remove placeholder pages that do not describe the project. + - Write source-backed pages from the project README, package exports, public types, examples, and tests. + - Add `title` and `description` frontmatter to each page. + - Configure navigation with `_nav.json` (top navbar) and `_meta.json` (sidebar) where the generated structure needs explicit labels or order. See [doc-structure-conventions.md](doc-structure-conventions.md) for examples. + - Follow official Rspress guidance for content features before inventing custom patterns: + - MDX and React components: + - Code blocks: + - Links: + - Static assets: + +6. **Wire project commands** + - Add or reuse scripts for docs development and build, such as `docs:dev` and `docs:build`, following the repo's package manager and workspace conventions. diff --git a/skills/rspress-docs-generator/references/doc-structure-conventions.md b/skills/rspress-docs-generator/references/doc-structure-conventions.md new file mode 100644 index 0000000..dc5c560 --- /dev/null +++ b/skills/rspress-docs-generator/references/doc-structure-conventions.md @@ -0,0 +1,117 @@ +# Documentation structure conventions + +Rspress generates navigation automatically when `rspress.config.ts` does not define `nav` or `sidebar`. Control the result with `_nav.json` (top navbar) and `_meta.json` (sidebar). + +Official reference: + +- Autogenerated navigation: + +- Place `_nav.json` at the docs root (or at the i18n language root such as `docs/en/`). +- Place `_meta.json` inside each subdirectory that needs explicit sidebar labels, order, or grouping. +- For clickable directories, add an `index.mdx` (or `index.md`) inside the directory. +- In leaf directories with only files, `_meta.json` can be omitted; Rspress sorts alphabetically. Prefix filenames with numbers such as `1-introduction.mdx` to customize order. + +## Example 1: simple Guide + API site + +```text +docs/ +├── _nav.json +├── guide/ +│ ├── _meta.json +│ ├── index.mdx +│ ├── getting-started.mdx +│ └── configuration.mdx +└── api/ + ├── _meta.json + ├── index.mdx + └── commands.mdx +``` + +`docs/_nav.json`: + +```json +[ + { "text": "Guide", "link": "/guide/", "activeMatch": "/guide/" }, + { "text": "API", "link": "/api/", "activeMatch": "/api/" } +] +``` + +`docs/guide/_meta.json`: + +```json +[ + { "type": "file", "name": "index", "label": "Overview" }, + "getting-started", + "configuration" +] +``` + +`docs/api/_meta.json`: + +```json +[{ "type": "file", "name": "index", "label": "Overview" }, "commands"] +``` + +## Example 2: site with grouped sections + +A larger site can use `dir-section-header` to group related directories in the sidebar. + +```text +docs/ +├── _nav.json +├── guide/ +│ ├── _meta.json +│ ├── start/ +│ │ ├── index.mdx +│ │ ├── introduction.mdx +│ │ └── getting-started.mdx +│ ├── basic/ +│ │ ├── index.mdx +│ │ └── auto-nav-sidebar.mdx +│ └── advanced/ +│ └── custom-theme.mdx +└── api/ + ├── _meta.json + ├── index.mdx + └── config/ + ├── _meta.json + ├── index.mdx + └── build.mdx +``` + +`docs/guide/_meta.json`: + +```json +[ + { "type": "dir-section-header", "name": "start", "label": "Getting Started" }, + { "type": "dir-section-header", "name": "basic", "label": "Features" }, + { "type": "dir-section-header", "name": "advanced", "label": "Advanced" } +] +``` + +`docs/api/_meta.json`: + +```json +[ + { "type": "section-header", "label": "Overview" }, + { "type": "file", "name": "index", "label": "API Overview" }, + { "type": "section-header", "label": "Config" }, + { "type": "dir", "name": "config", "label": "Config Options" } +] +``` + +## Example 3: i18n layout + +For multilingual sites, place `_nav.json` inside each language root and keep the same directory shape across locales. + +```text +docs/ +├── en/ +│ ├── _nav.json +│ ├── guide/ +│ └── api/ +└── zh/ + ├── _nav.json + ├── guide/ + └── api/ +``` diff --git a/skills/rspress-docs-generator/references/maintain-docs-for-prs.md b/skills/rspress-docs-generator/references/maintain-docs-for-prs.md new file mode 100644 index 0000000..d64a52c --- /dev/null +++ b/skills/rspress-docs-generator/references/maintain-docs-for-prs.md @@ -0,0 +1,31 @@ +# Maintain Docs For PRs + +Use this path when a Rspress v2 docs site already exists. + +1. **Connect docs work to the change** + - If a PR already exists, read its title, description, linked issues, and the full PR diff. + - If no PR exists yet, inspect the current branch diff against the base branch using `git merge-base` and `git diff`. + - Identify user-facing changes: new APIs, config options, CLI flags, plugins, behavior changes, migration notes, deprecations, examples, or breaking changes. + - Use the PR title or conventional commit category as one signal, but also exercise independent judgment about whether the change affects users. + - If the change has no user-facing impact, report that no docs update is needed and explain why. + +2. **Update the right pages** + - Modify existing pages before adding new pages when the change belongs in an established guide or API reference. + - Add new pages only for new workflows or concepts that need their own navigation entry. + - Keep examples minimal, runnable, and version-accurate. + - Add or update `description` frontmatter for every touched or created doc page. + - Update `_meta.json` whenever a new page should appear in sidebar or navigation. See [doc-structure-conventions.md](doc-structure-conventions.md) for examples. + - Use official Rspress docs to confirm syntax and conventions before adding new patterns: + - Frontmatter: + - MDX and React components: + - Links: + - Autogenerated navigation: + +3. **Respect existing docs conventions** + - Match the site's language, tone, directory structure, i18n layout, frontmatter style, and MDX component patterns. + - For i18n sites, update all required locales or explicitly note which locale remains pending. + - Prefer first-class Rspress options and documented theme APIs over custom workarounds. + +4. **Validate the documentation** + - Run the docs build from the Rspress project directory or through the repo's root script. + - If docs build is expensive or unavailable, at least validate changed Markdown/MDX structure, links, imports, navigation files, and frontmatter. diff --git a/skills/rspress-docs-generator/references/migrate-rspress-v1.md b/skills/rspress-docs-generator/references/migrate-rspress-v1.md new file mode 100644 index 0000000..ed9e228 --- /dev/null +++ b/skills/rspress-docs-generator/references/migrate-rspress-v1.md @@ -0,0 +1,10 @@ +# Migrate Rspress v1 + +Use this path when a docs site exists but depends on Rspress v1 packages or imports. + +1. Follow the official migration guide: + - Migration guide: + - Legacy Rspress 1.x docs: +2. Apply the changes the guide requires: package versions, config file, imports, theme code, plugin usage, and scripts. +3. Keep iterating until the docs site builds successfully on Rspress v2. +4. Only after the migration build passes, continue with [Maintain Docs For PRs](maintain-docs-for-prs.md) if the current task also includes feature documentation.