docs: generate description for all documentations

.agents/skills/rspress-description-generator/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rspress-description-generator
+description: Generate and maintain description frontmatter for Rspress documentation files (.md/.mdx). Use when a user wants to add SEO descriptions, improve search engine snippets, generate llms.txt metadata, prepare docs for AI summarization, or batch-update frontmatter across an Rspress doc site. Also use when adding new documentation pages to an Rspress project — every new doc file needs a description.
+---
+
+# 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>

skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "rspress-description-generator": {
+      "source": "rstackjs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "ca2693ca055d1b4e5903bdfacab522f46ca0e13cbc5db59e6c9589fdc8efc6ad"
+    }
+  }
+}

website/docs/en/api/javascript-api/core.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild JavaScript API, covering createRsbuild, loadConfig, loadEnv and related methods.'
+---
+
 # Rsbuild core
 
 Rsbuild offers these core methods.

website/docs/en/api/javascript-api/environment-api.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild JavaScript API, covering Environment context, Environment API and related methods.'
+---
+
 # Environment API
 
 Here you can find all environment APIs.

website/docs/en/api/javascript-api/instance.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild JavaScript API, covering rsbuild.context, rsbuild.build, rsbuild.startDevServer and related methods.'
+---
+
 # Rsbuild instance
 
 This section describes all the properties and methods on the Rsbuild instance object.

website/docs/en/api/javascript-api/server-api.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild JavaScript API, covering How to use, Example, Shared API and related methods.'
+---
+
 # Server API
 
 Rsbuild provides server APIs for both dev and preview servers, available through configuration, plugin hooks, and JavaScript API.

website/docs/en/api/javascript-api/types.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild JavaScript API, covering RsbuildInstance, RsbuildConfig, NormalizedConfig and related methods.'
+---
+
 # Rsbuild types
 
 This section describes some of the type definitions provided by the Rsbuild.

website/docs/en/api/start/index.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Overview of the Rsbuild JavaScript API, including core methods, instance APIs, environment APIs, and server APIs.'
+---
+
 # JavaScript API
 
 Rsbuild provides a comprehensive JavaScript API for developers to build higher-level tools or frameworks on top of Rsbuild.

website/docs/en/community/index.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Rsbuild community resources covering release policy, communication channels, team information, blogs, examples, and contribution links.'
+---
+
 # Rsbuild community
 
 ## Version

website/docs/en/community/releases/index.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Browse Rsbuild release notes by version to track new features, important changes, and historical updates.'
+---
+
 # Overview
 
 ## Changelog

website/docs/en/community/releases/v0-1.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.1, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2023-11-22 08:00:00
 ---
 

website/docs/en/community/releases/v0-2.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.2, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2023-12-11 08:00:00
 ---
 

website/docs/en/community/releases/v0-3.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.3, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-01-10 08:00:00
 ---
 

website/docs/en/community/releases/v0-4.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.4, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-02-06 08:00:00
 ---
 

website/docs/en/community/releases/v0-5.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.5, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-03-19 08:00:00
 ---
 

website/docs/en/community/releases/v0-6.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.6, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-04-10 18:00:00
 ---
 

website/docs/en/community/releases/v0-7.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 0.7, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-05-28 18:00:00
 ---
 

website/docs/en/community/releases/v1-0.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Release notes for Rsbuild 1.0, covering new features, important changes, ecosystem updates, and migration notes.'
 published_at: 2024-09-10 18:00:00
 ---
 

website/docs/en/config/dev/asset-prefix.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Set the URL prefix of static assets in development mode.'
+---
+
 # dev.assetPrefix
 
 - **Type:** `boolean | string | 'auto'`

website/docs/en/config/dev/browser-logs.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Controls whether to forward browser runtime errors to the terminal.'
+---
+
 # dev.browserLogs
 
 - **Type:**

website/docs/en/config/dev/cli-shortcuts.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Customize CLI shortcuts by providing a function that receives the default shortcuts array and returns a new one.'
+---
+
 # dev.cliShortcuts
 
 - **Type:**

website/docs/en/config/dev/client.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Configure the client code injected by Rsbuild during the development process. This can be used to set the WebSocket URL for HMR.'
+---
+
 # dev.client
 
 Configure the client code injected by Rsbuild during the development process. This can be used to set the WebSocket URL for HMR.

website/docs/en/config/dev/hmr.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Refer to Hot Module Replacement for more information.'
+---
+
 # dev.hmr
 
 - **Type:** `boolean`

website/docs/en/config/dev/lazy-compilation.mdx

@@ -1,3 +1,7 @@
+---
+description: "Enable lazy compilation (compilation on demand), implemented based on Rspack's lazy compilation feature."
+---
+
 # dev.lazyCompilation
 
 - **Type:**

website/docs/en/config/dev/live-reload.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Whether to reload the page when source files are changed.'
+---
+
 # dev.liveReload
 
 - **Type:** `boolean | { html?: boolean }`

website/docs/en/config/dev/progress-bar.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Whether to render progress bars to display the build progress.'
+---
+
 # dev.progressBar
 
 - **Type:**

website/docs/en/config/dev/watch-files.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Watch specified files and directories for changes. When a change is detected, it can trigger a page reload or restart the dev server.'
+---
+
 # dev.watchFiles
 
 - **Type:**

website/docs/en/config/dev/write-to-disk.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Controls whether the build output from development mode is written to disk.'
+---
+
 # dev.writeToDisk
 
 - **Type:** `boolean | ((filename: string) => boolean)`

website/docs/en/config/environments.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Rsbuild supports building outputs for multiple environments. You can use environments to define different Rsbuild configurations for each environment.'
+---
+
 # environments
 
 Rsbuild supports building outputs for multiple environments. You can use `environments` to define different Rsbuild configurations for each environment.

website/docs/en/config/html/app-icon.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild html.app-icon option, including behavior, defaults, configuration details, and usage examples.'
+---
+
 # html.appIcon
 
 - **Type:**

website/docs/en/config/html/crossorigin.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Set the crossorigin attribute of the script and style tags.'
+---
+
 # html.crossorigin
 
 - **Type:** `boolean | 'anonymous' | 'use-credentials'`

website/docs/en/config/html/favicon.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild html.favicon option, including behavior, defaults, configuration details, and usage examples.'
+---
+
 # html.favicon
 
 - **Type:** `string ｜ Function`

website/docs/en/config/html/inject.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Reference for the Rsbuild html.inject option, including behavior, defaults, configuration details, and usage examples.'
+---
+
 # html.inject
 
 - **Type:** `'head' | 'body' | boolean | Function`

website/docs/en/config/html/meta.mdx

@@ -1,3 +1,7 @@
+---
+description: 'If the HTML template used in the current project already contains the charset or viewport meta tags, then the tags in the HTML template take precedence.'
+---
+
 # html.meta
 
 - **Type:** `Object | Function`

website/docs/en/config/html/mount-id.mdx

@@ -1,3 +1,7 @@
+---
+description: 'By default, the root element is included in the HTML template for component mounting. The element id can be modified through mountId.'
+---
+
 # html.mountId
 
 - **Type:** `string`

website/docs/en/config/html/output-structure.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Define the directory structure of the HTML output files.'
+---
+
 # html.outputStructure
 
 - **Type:** `'flat' | 'nested'`

website/docs/en/config/html/script-loading.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Specifies how script tags generated by Rsbuild are loaded.'
+---
+
 # html.scriptLoading
 
 - **Type:** `'defer' | 'blocking' | 'module'`