rspress-description-generator

Rspress 描述生成器

Rspress frontmatter 中的 description 字段会生成 <meta name="description" content="..."> 标签，用于搜索引擎摘要、社交媒体预览，以及 llms.txt 等面向 AI 的格式。

第 1 步 — 定位文档根目录

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

第 2 步 — 检测 i18n 结构

Rspress i18n 项目会将语言子目录（例如 en/、zh/）直接放在文档根目录下：

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

检查文档根目录是否包含语言子目录（例如 en、zh、ja、ko 等两字母代码）。如果有，则分别处理每个语言目录——描述所用语言应与内容语言一致。

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

第 3 步 — 扫描并处理文件

在文档根目录下使用 glob 匹配 **/*.md 和 **/*.mdx。排除：

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

对于每个文件：

1. 读取文件。
2. 检查 frontmatter 中是否已有 description。 如果存在且非空，则跳过。
3. 检查 frontmatter 中的 pageType。 对于 home 页面，应根据 hero.text / hero.tagline 字段或 features 列表生成描述，而不是根据正文内容生成。
4. 按照下方的写作指南生成描述。
5. 将 description 插入 frontmatter：

   • 如果文件的 frontmatter 中有 title 字段，则在 title 下一行插入 description。

   • 如果文件的 frontmatter 中没有 title，则将 description 作为第一个字段插入。

   • 如果文件没有 frontmatter 块，则添加：

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

YAML 格式

大多数描述可以使用不加引号的 YAML 字符串：

description: Step-by-step guide to setting up your first Rspress site

如果描述中包含冒号、引号或其他 YAML 特殊字符，则用双引号括起来：

description: 'API reference for Rspress configuration: plugins, themes, and build options'

第 4 步 — 批量处理

对于文件较多的站点，可通过并行调用 Agent 同时处理互不相关的文件。按目录分组（例如先处理 guide/ 中的所有文件，再处理 api/ 中的所有文件），以保持各部分的关注点和风格一致。

处理完所有文件后，快速扫描以确保没有遗漏——重新执行 glob 匹配，并检查是否还有文件缺少 description。

描述写作指南

描述面向三类受众：搜索引擎（Google 摘要）、AI 系统（llms.txt、摘要生成）和人类读者（浏览搜索结果）。好的描述能同时满足这三类受众的需求。

规则

• 长度：50–160 个字符。少于 50 个字符会让搜索引擎难以理解；超过 160 个字符则会在摘要中被截断。
• 语言：与文档内容一致。中文文档使用中文描述，英文文档使用英文描述。
• 直截了当：说明页面涵盖的内容。避免以“This document”“This page”“Learn about”等开头——直接说明具体内容。
• 具体明确：提及页面涉及的具体技术、API 或概念。“配置用于搜索、分析和国际化的 Rspress 插件”胜过“如何使用插件”。
• 不要使用 Markdown：仅使用纯文本，不要使用格式语法。

示例

好的：

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

不好的：

描述	原因
“关于插件”	太笼统——是哪些插件？关于它们的什么内容？
“此页面介绍如何配置 Rspress 主题”	“此页面介绍如何”浪费字符
“了解 Rspress 的一切！”	空洞的宣传语，没有说明具体内容

文档

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