docs(website): generate description for all documentations (#1537)

Author: Timeless0911

.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: 'Use Rslib core APIs such as createRslib, loadConfig, defineConfig, and environment loading in JavaScript workflows.'
+---
+
 # Rslib core
 
 This chapter introduces some of the core methods provided by Rslib.

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

@@ -1,3 +1,7 @@
+---
+description: 'Use the Rslib instance API for builds, Module Federation dev servers, config inspection, and lifecycle control.'
+---
+
 # Rslib instance
 
 This section describes all the properties and methods on the Rslib instance object.

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

@@ -1,3 +1,7 @@
+---
+description: 'Reference the TypeScript types exported by Rslib for configs, APIs, instance methods, plugins, and Rsbuild or Rspack types.'
+---
+
 # Rslib types
 
 This section describes some of the type definitions provided by the Rslib.

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

@@ -1,3 +1,7 @@
+---
+description: 'Get started with the Rslib JavaScript API in Node.js, Deno, or Bun using createRslib and instance methods.'
+---
+
 # JavaScript API
 
 Rslib provides a comprehensive JavaScript API for developers to directly use Rslib's capabilities in JavaScript or TypeScript code.

website/docs/en/blog/index.mdx

@@ -1,5 +1,6 @@
 ---
 title: Overview
+description: 'Browse Rslib release announcements, project updates, and articles about library development with Rspack and Rsbuild.'
 sidebar: false
 ---
 

website/docs/en/blog/introducing-rslib.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Learn why Rslib was built on Rspack and Rsbuild, and how it delivers multiple output formats, ecosystem reuse, and performance.'
 date: 2025-05-14 10:00:00
 sidebar: false
 ---

website/docs/en/config/index.mdx

@@ -1,4 +1,5 @@
 ---
+description: 'Browse the Rslib configuration overview, including lib options, inherited Rsbuild settings, and links to every reference page.'
 pageType: doc-wide
 outline: false
 ---

website/docs/en/config/lib/auto-extension.mdx

@@ -1,3 +1,7 @@
+---
+description: 'Configure lib.autoExtension to derive output file extensions from the selected library format and output mode.'
+---
+
 # lib.autoExtension
 
 - **Type:** `boolean`