我做技术写作这些年听得最多的一句抱怨就是“我写了README怎么大家还是看不懂”直到有一天我把某个项目的文档站整站导出丢给一套基于向量检索的问答系统去测试AI给出的答案让我自己都尴尬关键参数说错、安装步骤顺序颠倒、还把两个不同版本的API混在了一起。那时候我才非常确定一件事——你的文档AI根本看不懂很多时候不是大模型能力不够而是文档本身的结构对于机器来说就是一锅粥。最近社区里那条“rspress-20撕开了技术写作的遮羞布”的帖子本质就是在聊这件事现代文档工具比如Rspress到底改了什么又逼我们重新审视什么。这篇内容不是单纯测评某个框架而是想借Rspress这个切入点把“AI可读性”这个以往很少有人认真对待的技术写作问题拆开讲清楚。适合给文档维护者、开源项目作者、前端开发者以及所有写过“看起来像说明文但机器完全无法解析”的文档的人参考。1. 你的文档为什么AI根本看不懂1.1 从一次“AI问答翻车”说起先说一个真实的翻车现场。当时我有一个项目文档内容组织得很“整齐”首页是简介、下面分安装、配置、API列表几个板块。从人的视角看排版没问题加粗也用了换行也讲了规矩。但是当我用支持本地知识库问答的AI工具去测试时用户询问“这个工具的默认端口是什么”AI从文档里抽了一段“端口设置”的文字然后自作主张地把示例环境变量里的数字当成默认值给了我。为什么会出现这种情况因为AI读文档靠的不是“肉眼看到的排版”而是从HTML、Markdown段落里提取的纯文本结构。你的文档里如果只有一段连续的大段文字AI无法区分哪句话是介绍、哪句话是规定、哪句话是示例。它只能全文一起塞进上下文再由模型猜重点。人类读者靠字体大小、行间距、加粗颜色来判断“这是标题”“这是正文”机器并没有这些视觉线索后仍然能准确理解的本领。这个问题在技术文档里尤其严重。技术文档本质上是一个“结构化数据集”有环境要求、参数表、命令、返回类型、错误码。你用自然语言把这堆数据串成散文人读起来也许流畅但机器会把散文里的每一个字都当同等重要信息最终导致主次不分。1.2 人眼和机器眼看到的不是同一份文档继续往下想一层传统文档工具Word、PDF、甚至很多在线Wiki生成的页面给人看是清晰的但机器能拿到的“解析树”非常贫瘠。你去用解析库跑一份PDF文档得到的结果往往是一堆毫无层级的文字流连列表序号都丢了。这就像你把客厅照片拿给一位没见过你家户型图的陌生人问他“承重墙在哪里”他只能对着画面里的沙发、电视柜瞎猜。现代文档站生成工具的底层逻辑完全不一样。Rspress这类框架会把每篇MDX文件编译成一段语义化的HTML结构H1、H2、H3、nav、article、table、ol都有明确标签。对AI和爬虫来说它们不需要“看懂”画面只需要解析DOM里面h2与随后的段落关系就能判断“这段内容是上一级的子项”。这个差异是“机器能读懂”和“机器只能瞎猜”的分界线。很多人误以为只要内容够长、够全AI就自然能读明白。实际上内容全不全是一回事结构可不可解析是另一回事。一份只有两行字但结构清楚的文档比一万字流水账更容易被AI正确使用。Rspress这类工具最本质的作用不是帮你把页面做得漂亮而是强制你的内容进入一个可解析的结构框架里。1.3 写作习惯里的“上下文断层”写文档的人还有一个隐性问题默认读者“已经知道背景”。比如文档写“安装依赖后运行npm run dev”但“依赖”是什么是系统依赖还是项目依赖需要Node版本多少没有前置说明。人如果遇到问题会结合自己的项目经验去猜AI没有这个能力——尤其当它从向量库检索时可能只抽到了“安装依赖后运行npm run dev”这一句话上下文全丢。还有一类典型问题是滥用指代词“这个功能非常实用”“上一步提到的配置项”“反正按照之前的方案”。AI在单篇页面里做抽取时遇到“这个”“之前”往往无法定位指代对象生成答案就只能含糊带过。这就是我理解的“技术写作的遮羞布”表面上看文档该有的章节都有但经不起机器可读性这一层检验。很多团队文档站做得热闹导航、搜索、暗色模式应有尽有但把网页正文转成纯文本之后逻辑链条是断的。AI提问基于这种文本回答自然不忍直视。2. 现代文档工具悄悄改了什么2.1 从“排版漂亮”到“结构可解析”Rspress这类工具给了我们一次重新思考内容组织的机会。它做的事简单说就三件把MDX编译为静态站点、为全文生成搜索索引、为每个页面生成独立URL。这三件事看起来不稀奇但对机器可读性影响深远。第一静态站点输出的是语义化HTML不是一张被浏览器渲染后的“图片”。爬虫、AI内容抽取器可以直接读取完整的标题树、表格结构、代码块位置。第二全文索引意味着搜索不再只是按文件名匹配而是按内容关键词匹配。这其实是RAG检索增强生成场景的基础——AI问答系统要能从大量文档里找答案必须有可靠的全文索引做前置。第三独立URL让每个页面都拥有独立上下文。AI在抓取文档站时可以按路径理解“这是一个API配置页”而不是“某个主页里的一段内容”。也许有人觉得普通Markdown文件放在Git仓库里不也一样吗区别在于Rspress对文档的“位置”和“关系”有明确约定。sidebar配置、目录层级、mdx文件名共同组成一张内容地图。人浏览左侧导航时看到的层级就是机器理解文档结构的依据。如果你的目录是乱的比如所有页面都平铺在顶层AI很难判断哪篇是入门文档、哪篇是深度参考。2.2 Frontmatter机器最先阅读的“图书扉页”Rspress里每篇文档顶部都可以写一段Frontmatter元信息。这个东西非常像一本图书的扉页书名、作者、简介、分类。对于人类读者它更多是控制展示位置和标签对于机器它是理解整个文档属性的关键入口。举一个最简单的例子一篇文档如果只给了文件名/api/config.mdx机器只能根据路径猜测内容和API配置相关。但你写下title、description、keywords之后搜索引擎的摘要、AI索引的向量化片段都会优先参考这些字段。尤其是description一定不能随手填它决定了AI在处理相关提问时第一眼看到的内容。把description写成“面向新用户的安装步骤涵盖环境准备、权限设置、启动验证”这类概括句比写“安装说明”这种短词有用得多。我更建议把keywords当作“文档归属标签”来用。哪怕不打算做SEO这些标签也会进入站内搜索索引。很多团队文档找不到东西原因之一就是页面标题起得千奇百怪但Frontmatter里没有规范的标签归口。2.3 MDX把文档变成信息积木Rspress最让人上瘾的一点是它允许在Markdown里写React组件也就是MDX。这不是花架子。它意味着你可以在文档里插入一个“参数表格组件”传入一份数据表格自动渲染或者插入一个“步骤条组件”把几步操作变成带有序语义的编号列表。这样出力点就变了你不必重复劳动而是把文档拆成了多个可组合的信息积木。站在AI可读性角度MDX最大的价值是让“格式表达”和“内容表达”剥离。举个例子你想写“安装步骤”传统做法是写一段带换行的文字“首先下载安装包。然后解压到指定目录。最后运行启动命令。”AI读起来需要自己推断这是有先后关系的步骤。但在MDX里你可以用一个Steps组件包住三个子项最终生成的HTML会带有序列表标签机器一眼就能知道这是三个顺序操作。我特别建议做开源项目的朋友认真用一下这个能力API文档里动不动几十个参数用纯文本写出来别说AI人看着都头大。把参数表做成标准表格或者组件这部分信息的可读性直接上一个台阶。3. 实操用Rspress搭一份AI看得懂的文档3.1 初始化项目与目录设计先不说大道理直接把搭建过程走一遍。环境需要Node 18以上和pnpm如果你还没装pnpm直接用corepack启用也可以。pnpm create rspresslatest docs-site cd docs-site pnpm install pnpm run dev默认模板会生成一个docs目录里面有一篇首页mdx和快速开始页面。我先推荐一套适合大多数项目的目录结构docs/ index.mdx guide/ getting-started.mdx installation.mdx api/ config.mdx cli.mdx faq.mdx这套结构遵循两个原则每篇文档独立成一页不被塞进巨型文档页面按“指南”和“API参考”区分开让AI在检索时能分辨教程类内容与参考类内容。指南页里讲概念和流程API参考页里只讲参数和返回值这种分工对机器非常友好。AI回答“怎么安装”时会倾向于检索getting-started或installation页面回答“某个配置项是什么意思”时会定位到API页面。3.2 写一份高质量Frontmatter打开一篇新文档先把Frontmatter写完整。这里给出一个可以直接改的模板--- title: 安装配置指南 description: 面向新用户的完整安装步骤包含环境要求、依赖安装和首次启动验证。 keywords: - 安装 - 配置 - 环境要求 - 快速开始 sidebar_position: 2 ---title不要包含项目名以外多余的修饰词最好让读者一眼看出这是什么场景的文档description尽可能写成“一句话概括完整流程”而不是宣传语sidebar_position决定展示顺序但它也影响导航树的层级权重建议和文档的学习路径保持一致。你可以把Frontmatter理解为“机器读文档前的开胃菜”。搜索引擎在生成搜索结果摘要时优先读取descriptionAI索引构建时title和description会作为重要的语义锚点。跳过它们等于让机器从正文大海里捞针。3.3 正文写作的“语义三件套”我总结过一套适合绝大多数技术文档的“语义三件套”层级标题、有序步骤、参数表格。不是说所有地方都得用而是在凡是能用它们替代大段文字的场景尽量用。层级标题这块容易被忽略的是标题文字本身要具体。不要写“介绍”“操作”要写“如何设置代理端口”“在Linux下安装依赖”。因为AI在做段落抽取时会以标题作为中心词然后匹配下面的正文。一个叫“操作”的标题对理解没有任何帮助而“如何设置代理端口”这个标题直接就是最好的检索关键词。有序步骤要使用Markdown有序列表而不是自己写“第一步”“第二步”。原因很简单有序列表最终生成的HTML是ol标签AI可以明确知道这是序列动作你自己写的“第一步”在纯文本里和普通句子没有任何区别。参数表格强力推荐用标准Markdown表格特别是参数名、类型、默认值、说明四列齐全的那种。我在实际项目中见过太多API文档把参数说明用散文写在段落里结果AI回答时连参数类型都分不清。3.4 补充JSON-LD结构化数据如果你想让AI问答场景下的效果更进一步可以在页面里注入JSON-LD结构化数据。以FAQ为例如果你的文档页里包含常见问题解答给它标注成FAQPage结构搜索引擎和AI工具能直接识别“这是一个问题配一个答案”的格式而不是靠猜。Rspress基于MDX的能力你可以在文档页中引入自定义组件来注入这段结构化数据。示例思路如下import { Head } from rspress/runtime; Head script typeapplication/ldjson {JSON.stringify({ context: https://schema.org, type: FAQPage, mainEntity: [ { type: Question, name: 默认端口是多少, acceptedAnswer: { type: Answer, text: 默认端口是8080可以在配置文件中修改。 } } ] })} /script /Head这段代码不是必须的但对部署后搜索收录和AI精准抽取很有帮助。我自己的经验是把文档里的高频问答案例用JSON-LD标注一遍之后同类问题被AI回答的正确率有明显提升。4. 常见问题与排查技巧实录4.1 部署后搜索引擎搜不到新文档这是很常见的情况先别怀疑内容质量问题。排查顺序如下第一确认站点是否生成了sitemap.xml。Rspress这类SSG工具通常可以配置自动生成如果没开启搜索引擎的爬虫就得靠页面互相链接去发现内容新页面收录会慢很多。第二检查robots.txt是否误屏蔽了文档路径。很多项目模板里默认带了robots如果没有配置允许字段可能导致所有页面都不被索引。第三确认部署平台是否返回了正确的状态码。有些纯前端托管平台如果不配置重写规则访问/api/config这类带目录的路径时可能返回404爬虫和AI都会认为这个页面不存在。我踩过最深的坑是本地开发一切正常部署后却没有HTML内容爬到。后来发现是部署平台对HTML文件做了缓存导致新发布内容不能即时刷新。解决办法是在CI里给文档站点加上缓存清理步骤。4.2 AI问答还是“看不出重点”如何验证文档上线了AI问答效果仍然不好。这个时候要回到内容层面检查而不是继续调部署参数。我的建议是做一个“纯文本测试”把每个文档页面的正文复制出来用纯文本形式读一遍。重点观察三件事第一每段开头第一句话是不是能概括整段第二有没有一个页面对应一个主题第三代码块里的命令是否配了前置说明。如果纯文本读起来逻辑通顺、每段有明确的“主旨句”AI拿到它做向量化索引时检索命中率也会提高。你还可以把文档站接入一个支持RAG的工具对本地做一组提问测试。问题设计要贴近用户真实的提问习惯而不是只问文档标题里的词。比如你的文档标题叫“安装配置指南”但你真正该问的是“怎么修改默认端口”因为用户脑子里往往没有文档标题的概念只有具体问题。用这种问题去检索你很快就能发现自己文档在“信息离题”上的问题。4.3 表格与列表的“过犹不及”我遇到过一种反向极端为了追求“语义化”作者把所有内容都强行做成表格和列表把文档拆得七零八碎。表格确实对机器友好但它更适合“对照关系”明确的数据。拿参数表来说列是参数名、类型、默认值、说明这很合适。但如果让你写一段“使用场景介绍”塞进表格就是灾难每行塞一半句话提取时AI完全无法理解上下文。列表也一样。列表层级别超过两层超过之后不管是人还是机器都极易迷失。一个简单的判断标准如果一个列表项里面你还想再加注释、加示例那就说明这个信息应该用一个小标题章节来承载。文档的价值是清晰传递信息不是给AI搞数据压缩。4.4 版本漂移让AI“学到过期参数”代码产品有个经典问题文档更新跟不上版本发布。你在文档里写了旧端口号代码早就改成新配置了这时候AI基于文档给出的答案就会出错而且错误得很“自信”。解决思路是给文档站点绑定版本概念。Rspress支持多版本文档目录把当前版本和旧版本分区管理比如在docs/v1、docs/v2下面分别维护。然后在站点顶部明确标注“当前文档针对v2版本”。最理想的状态是文档内容和npm包版本联动发版时自动归档旧文档并标记为archived。这样AI检索时如果命中旧文档至少还有机会通过版本标识判断信息可能过期而不是把旧参数当现行标准。我见过不少项目用脚本在CI阶段做“死链检查”和“示例代码编译检查”但很少有人顺手做“文档关键词与代码常量一致性检查”。其实可以写一个简单的静态检查脚本把正文里的端口号、包名称、命令参数抽出来和代码配置比对不一致直接让CI变红。这个脚本维护成本不高收益却极高。5. 几个值得养成的写作习惯最后分享几个我最近一直在坚持的、和工作工具无关的小习惯。第一个是每次动笔写文档之前先花两分钟写Frontmatter和一句话摘要。不要小看这两个动作它逼着你想清楚这篇文档到底想让机器和读者记住什么。第二个是段落尽量“一段一事”每段第一句就是主旨其余句子围绕主旨展开。机器抽取信息时段落开头部分权重本来就高人读起来也更省力。第三个是凡涉及版本号、端口号、命令参数必须落成表格或代码注释不再写进散文里。这样信息出错时定位与修改都很快。第四个习惯是定期把文档站的正文下载下来用纯文本格式重读一遍。你会发现很多“页面里看起来没问题抽出来读却前言不搭后语”的段落。这个检测方法不需要任何高级工具却比很多花哨的辅助系统都能暴露问题。我现在写文档或者帮团队做文档梳理默认就会按这套逻辑来先保证机器能读懂结构再去考虑文笔和排版。Rspress给我的最大启发不是它作为一个工具多好用而是它把我从“写完就行”的惯性里拉了出来逼我重新审视内容组织的每一层。如果你手上的文档也面临“AI读不懂”的窘境不妨从今天开始把每篇页面当成一个独立的信息节点来重新整理。先把标题写清楚、描述写准确、参数落成表格再去看AI的回答质量有没有变化。实测下来你会发现变化比想象中来得快。