rstackjs/rspress-description-generator

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:

     ---
     description: Your generated description here
     ---
     

YAML formatting

Most descriptions can be bare YAML strings:

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:

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