问题

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

为什么重要

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

方法

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

实施

1. 严格的标题层级

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

• # 标题：页面的主要主题。
• ## 主要概念：一个原子化的、高层级的话题。
• ### 细节：该概念的具体子任务或属性。

• ❌ 糟糕：因为喜欢较小的字号而在 # 之后直接使用 ###。
• ✅ 正确：# 安装 之后跟着 ## 先决条件，然后是 ### 系统要求。

2. 媒体的描述性元数据

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

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

3. 显式的代码块标记

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

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

4. 语义容器

使用 标注 (Callouts) 而不是通用的引用块来表达意图。docmd 的语义容器可帮助 AI 模型区分核心指令与补充提示或警告。

权衡

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