Rspress Description Generator
The
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
- Find the Rspress config file. Search for , , , or . It may be at the project root or inside a subdirectory like .
- Read the config and extract the option.
- The value might be a plain string () or a JS expression (
root: path.join(__dirname, 'docs')
- If is set, resolve it relative to the config file's directory.
- If is not set, default to relative to the config file's directory.
- Confirm the directory exists. If neither nor the configured root exists, check for as a fallback.
Step 2 — Detect i18n structure
Rspress i18n projects place language subdirectories (e.g.,
,
) 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
,
,
,
, 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
and
under the docs root. Exclude:
- , build output (, , )
- / (sidebar/nav config files, not doc pages)
- directories (reusable snippets included via , not standalone pages)
For each file:
- Read the file.
- Check for existing in frontmatter. If it exists and is non-empty, skip.
- Check in frontmatter. For pages, derive the description from the / fields or the features list, not from body content.
- Generate a description following the writing guidelines below.
- Insert into frontmatter:
-
If the file has frontmatter with a
field, insert
on the line after
.
-
If the file has frontmatter without
, insert
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
, then all in
) 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 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