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