rspress-description-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspress Description Generator

Rspress 描述生成器

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.

Rspress frontmatter中的

description

字段会生成

<meta name="description" content="...">

标签，用于搜索引擎摘要、社交媒体预览以及llms.txt这类面向AI的格式。

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/
```
.
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.
Confirm the directory exists. If neither
```
docs
```
nor the configured root exists, check for
```
doc
```
as a fallback.

找到Rspress配置文件。搜索
```
rspress.config.ts
```
、
```
.js
```
、
```
.mjs
```
或
```
.cjs
```
文件，它可能位于项目根目录或
```
website/
```
之类的子目录中。
读取配置并提取
```
root
```
选项。
- 该值可能是普通字符串（
```
root: 'docs'
```
  ）或JS表达式（
```
root: path.join(__dirname, 'docs')
```
  ）。无论哪种情况，都要确定解析后的目录路径。
- 如果设置了
```
root
```
  ，则相对于配置文件所在目录解析它。
- 如果未设置
```
root
```
  ，默认使用配置文件所在目录下的
```
docs
```
  目录。
确认目录存在。如果
```
docs
```
目录和配置的root目录都不存在，检查
```
doc
```
目录作为备选。

Step 2 — Detect i18n structure

步骤2 — 检测国际化（i18n）结构

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.

Rspress国际化项目会将语言子目录（如

en/

、

zh/

）直接放在文档根目录下：

docs/
├── en/
│   ├── guide/
│   └── index.md
└── zh/
    ├── guide/
    └── index.md

en

、

zh

、

ja

、

ko

等双字母代码）。如果存在，则单独处理每个语言目录——描述语言应与内容语言匹配。

如果没有语言子目录，则将整个文档根目录视为单语言站点。

Step 3 — Scan and process files

步骤3 — 扫描并处理文件

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:

Read the file.
Check for existing
description
in frontmatter. If it exists and is non-empty, skip.
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.
Generate a description following the writing guidelines below.
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
---
```

在文档根目录下匹配

**/*.md

和

**/*.mdx

文件，排除以下内容：

```
node_modules
```
、构建输出目录（
```
doc_build
```
、
```
.rspress
```
、
```
dist
```
）
```
_meta.json
```
/
```
_nav.json
```
（侧边栏/导航配置文件，非文档页面）
```
**/shared/**
```
目录（通过
```
@import
```
引入的可复用代码片段，非独立页面）

对于每个文件：

读取文件内容。
检查frontmatter中是否已有
description
。如果存在且非空，则跳过。
检查frontmatter中的
pageType
。对于
```
home
```
类型页面，从
```
hero.text
```
/
```
hero.tagline
```
字段或功能列表推导描述，而非从正文内容生成。
按照以下写作指南生成描述。
将
description
插入frontmatter：
- 如果文件的frontmatter包含
```
title
```
  字段，在
```
title
```
  字段的下一行插入
```
description
```
  。
- 如果文件的frontmatter没有
```
title
```
  字段，将
```
description
```
  作为第一个字段插入。
- 如果文件没有frontmatter块，则添加一个：
  yaml
```
---
description: 生成的描述内容
---
```

YAML formatting

YAML格式规范

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'

大多数描述可以直接使用YAML字符串：

yaml

description: 搭建首个Rspress站点的分步指南

如果描述包含冒号、引号或其他特殊YAML字符，需用双引号包裹：

yaml

description: 'Rspress配置API参考：插件、主题和构建选项'

Step 4 — Batch processing

步骤4 — 批量处理

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

对于包含大量文件的站点，使用并行代理调用同时处理独立文件。按目录分组（如先处理

guide/

下的所有文件，再处理

api/

下的所有文件），以保持每个章节的聚焦性和一致性。

处理完所有文件后，快速扫描确保没有遗漏——重新匹配文件并检查是否还有未添加

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.

描述服务于三类受众：搜索引擎（谷歌摘要）、AI系统（llms.txt、摘要生成）和人类（浏览搜索结果）。优质的描述需同时满足三者需求。

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.

长度：50–160字符。少于50字符对搜索引擎来说过于模糊；超过160字符会在摘要中被截断。
语言：与文档内容语言匹配。中文文档使用中文描述，英文文档使用英文描述。
直接明了：说明页面涵盖的内容。避免以“本文档”“本页面”“了解”开头——直接切入核心内容。
具体明确：提及页面涵盖的具体技术、API或概念。“为搜索、分析和国际化配置Rspress插件”比“如何使用插件”更优。
无Markdown：仅使用纯文本，不包含格式语法。

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

优秀示例：

内容	描述
插件开发指南	使用Node.js插件API和运行时钩子创建自定义Rspress插件
MDX组件使用	在MDX文档文件中导入并使用React组件
Rspress 快速开始	从安装到本地预览，搭建 Rspress 文档站点的完整流程
主题配置	自定义 Rspress 主题的导航栏、侧边栏、页脚和暗色模式
首页（pageType: home）	Rspress文档框架——快速、基于MDX的静态站点生成器

反面示例：

描述	原因
"关于插件"	过于模糊——哪些插件？涉及哪些内容？
"本页面讲解如何配置Rspress主题"	浪费字符在“本页面讲解如何”上
"了解关于Rspress的一切！"	营销话术，未说明具体内容

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

Frontmatter字段：https://rspress.rs/api/config/config-frontmatter
基础配置（
```
root
```
选项）：https://rspress.rs/api/config/config-basic
Rspress完整文档：https://rspress.rs/llms.txt