rspress-description-generator — Claude Code skill for Rspress docs

---
name: rspress-description-generator
description: Generate missing description frontmatter for Rspress Markdown/MDX pages, including new docs pages and site-wide SEO metadata updates.
---

# Rspress description generator

The `description` field in Rspress frontmatter generates `<meta name="description" content="...">` tags, which are used for search engine snippets, social media previews, and AI-oriented formats like llms.txt.

## Step 1 — locate the docs root

1. Find the Rspress config file. Search for `rspress.config.ts`, `.js`, `.mjs`, or `.cjs`. It may be at the project root or inside a subdirectory like `website/`.
2. Read the config and extract the `root` option.
   - The value might be a plain string (`root: 'docs'`) or a JS expression (`root: path.join(__dirname, 'docs')`). In either case, determine the resolved directory path.
   - If `root` is set, resolve it relative to the config file's directory.
   - If `root` is not set, default to `docs` relative to the config file's directory.
3. Confirm the directory exists. If neither `docs` nor the configured root exists, check for `doc` as a fallback.

## Step 2 — detect i18n structure

Rspress i18n projects place language subdirectories (e.g., `en/`, `zh/`) directly under the docs root:

```
docs/
├── en/
│   ├── guide/
│   └── index.md
└── zh/
    ├── guide/
    └── index.md
```

Check if the docs root contains language subdirectories (two-letter codes like `en`, `zh`, `ja`, `ko`, etc.). If so, process each language directory separately — the description language should match the content language.

If there are no language subdirectories, treat the entire docs root as a single-language site.

## Step 3 — scan and process files

Glob for `**/*.md` and `**/*.mdx` under the docs root. Exclude:

- `node_modules`, build output (`doc_build`, `.rspress`, `dist`)
- `_meta.json` / `_nav.json` (sidebar/nav config files, not doc pages)
- `**/shared/**` directories (reusable snippets included via `@import`, not standalone pages)

For each file:

1. **Read the file.**
2. **Check for existing `description` in frontmatter.** If it exists and is non-empty, skip.
3. **Check `pageType` in frontmatter.** For `home` pages, derive the description from the `hero.text` / `hero.tagline` fields or the features list, not from body content.
4. **Generate a description** following the writing guidelines below.
5. **Insert `description` into frontmatter:**
   - If the file has frontmatter with a `title` field, insert `description` on the line after `title`.
   - If the file has frontmatter without `title`, insert `description` as the first field.
   - If the file has no frontmatter block, add one:

     ```yaml
     ---
     description: Your generated description here
     ---
     ```

### YAML formatting

Most descriptions can be bare YAML strings:

```yaml
description: Step-by-step guide to setting up your first Rspress site
```

If the description contains colons, quotes, or other special YAML characters, wrap in double quotes:

```yaml
description: 'API reference for Rspress configuration: plugins, themes, and build options'
```

## Step 4 — batch processing

For sites with many files, use parallel agent calls to process independent files simultaneously. Group by directory (e.g., all files in `guide/`, then all in `api/`) to maintain focus and consistency within each section.

After processing all files, do a quick scan to ensure no files were missed — re-glob and check for any remaining files without `description`.

## Description writing guidelines

The description serves three audiences: search engines (Google snippet), AI systems (llms.txt, summarization), and humans (scanning search results). A good description helps all three.

### Rules

- **Length**: 50–160 characters. Under 50 is too vague for search engines; over 160 gets truncated in snippets.
- **Language**: Match the document content. Chinese docs get Chinese descriptions, English docs get English descriptions.
- **Be direct**: State what the page covers. Avoid starting with "This document", "This page", "Learn about" — jump straight to the substance.
- **Be specific**: Mention concrete technologies, APIs, or concepts the page covers. "Configure Rspress plugins for search, analytics, and internationalization" beats "How to use plugins."
- **No markdown**: Plain text only, no formatting syntax.

### Examples

**Good:**

| Content                    | Description                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- |
| Plugin development guide   | Create custom Rspress plugins using the Node.js plugin API and runtime hooks |
| MDX component usage        | Import and use React components in MDX documentation files                   |
| Rspress 快速开始           | 从安装到本地预览，搭建 Rspress 文档站点的完整流程                            |
| 主题配置                   | 自定义 Rspress 主题的导航栏、侧边栏、页脚和暗色模式                          |
| Home page (pageType: home) | Rspress documentation framework — fast, MDX-powered static site generator    |

**Bad:**

| Description                                             | Why                                              |
| ------------------------------------------------------- | ------------------------------------------------ |
| "About plugins"                                         | Too vague — which plugins? what about them?      |
| "This page explains how to configure the Rspress theme" | Wastes characters on "This page explains how to" |
| "Learn everything about Rspress!"                       | Marketing fluff, says nothing specific           |

## Documentation

- Frontmatter fields: <https://rspress.rs/api/config/config-frontmatter>
- Basic config (`root` option): <https://rspress.rs/api/config/config-basic>
- Full Rspress docs: <https://rspress.rs/llms.txt>