问题

人类读者依靠视觉线索、侧边栏导航和推断上下文来理解文档。然而，AI 代理和大型语言模型 (LLMs) 主要消费原始文本流。当文档缺乏严格的语义结构时，这些模型难以映射概念之间的关系，从而导致推理较差和不准确的编码建议。

为什么这很重要

如果你的文档未针对 LLM 进行优化，那么使用 GitHub Copilot、Cursor 或 ChatGPT 等工具的开发人员在处理你的软件时将会遇到更多的幻觉。这直接降低了开发人员的体验，因为用户通常会因为 AI 助手生成的错误而归咎于产品本身。

方法

从“视觉优先”的心态转变为 “语义优先” 的心态。使用标准的 Markdown 功能 —— 例如严格的标题层次结构、明确的代码块语言标签和描述性的替代文本 —— 为你的内容提供清晰、机器可读的路线图。docmd 通过 LLMs 插件 将这种结构处理成优化的输出。

实现

1. 严格的标题层次结构

避免为了纯粹的视觉效果而跳过标题级别。一致的层次结构允许 LLM 理解不同章节的范围和关系。

  • # 标题: 页面的主要主题。
  • ## 主要概念: 一个原子的、高层的话题。
  • ### 细节: 该概念的一个特定子任务或属性。
  • ❌ 较差: 在 # 之后立即使用 ###，只是因为你喜欢较小的字体。
  • ✅ 较好: # 安装 之后是 ## 前提条件，然后是 ### 系统要求。

2. 媒体的描述性元数据

由于 LLM 无法“看到”图像或图表，你必须在替代文本或相邻段落中提供架构上下文。

![系统架构：前端 React 应用程序通过 REST 与 Node.js API 通信，后者随后查询 Redis 缓存和 PostgreSQL 数据库。](../../static/img/architecture.png)

3. 明确的代码块标签

始终使用 语法高亮 为每个围栏代码块指定语言。这允许 LLM 正确解析代码的抽象语法树 (AST)。

// docmd.config.js
export default {
  plugins: ['llms']
};

4. 语义化容器

使用 标注 而不是通用的块引用来提供意图。docmd 的语义容器帮助 AI 模型区分核心指令与补充技巧或警告。

权衡

语义上的严谨要求作者具有自律性。你不能再将 Markdown 功能（如块引用或标题）纯粹用作装饰元素。然而，这种自律产生的文档对于 AI 代理和使用辅助技术的人类读者来说，其可访问性都将显著提高。

previous 大型仓库 next AI 就绪输出