如何改善文档 SEO

搜索引擎是用户查找文档最可靠的途径之一。当有人搜索”如何使用 [你的产品] 设置身份验证”时，优化良好的文档会将你的内容置于搜索结果的顶部，而不是 Stack Overflow 帖子或竞争对手的页面。

本指南涵盖了对文档 SEO 影响最大的技巧，从编写更好的页面标题到构建可维护的内部链接策略。

页面标题是最重要的页面 SEO 信号。它们告诉搜索引擎——和用户——页面到底涵盖了什么内容。

编写与用户搜索方式匹配的标题，而不是产品界面的标签。“身份验证”是一个产品标签。“如何对 API 请求进行身份验证”是一个搜索查询。

• 匹配用户意图：在适当的地方使用”如何”、“指南”或”参考”
• 将主要关键词放在标题靠前的位置
• 确保每个标题都是唯一的——重复的标题会让搜索引擎感到困惑

描述出现在搜索结果中页面标题的下方。好的描述即使在排名相同的情况下也能提高点击率。

• 概述用户将完成什么，而不仅仅是页面涵盖什么
• 自然地包含主要关键词
• 使用主动语态：“了解如何配置……”而不是”本页介绍……”

Mintlify 会根据 title 和 description frontmatter 自动生成 meta 标签。对于 Open Graph 图片、canonical URL 或自定义 robots 指令等高级配置，请参阅 SEO 配置参考。

关键词研究帮助你了解用户在查找文档涵盖的内容时实际输入的内容。

从你自己的数据开始： 如果你已将 Google Search Console 连接到文档，请查看”搜索结果”报告。最佳的优化目标是用户已经通过搜索找到你的查询，以及你出现了但排名不好的查询。

查找相关查询： Google Keyword Planner 和 Ahrefs Free Keyword Generator 等免费工具会显示有多少人搜索某个短语并建议相关术语。

• 页面标题和描述（影响最大）
• H2 和 H3 标题
• 页面的第一段
• 相关图片的替代文本

不要机械地重复关键词。文档应该读起来自然流畅。如果标题听起来很勉强，说明该关键词不适合那个部分。

标题结构有两个作用：帮助用户浏览页面，并告诉搜索引擎各主题之间的关系。

Mintlify 会根据 frontmatter 中的 title: 属性自动为每个页面创建 H1。切勿在页面正文中手动添加 H1。将其他所有内容组织为 H2 及以下级别：

## 主要部分 (H2)

### 子部分 (H3)

#### 细节 (H4, 谨慎使用)

将标题写成问题或意图短语。 比较：

以问题形式编写的标题更有可能出现在 Google 的”大家还在问”框中，该框出现在自然搜索结果之上，即使排名较低的页面也能获得点击。

内部链接在 SEO 方面有两个作用：帮助搜索引擎发现和理解你的内容，以及在页面之间传递排名权重。

在内容中链接到相关概念。 当你解释一个依赖于另一个概念的内容时，使用描述性锚文本进行链接：

<!-- 好的做法 -->
了解如何[配置你的 sitemap](/zh/optimize/seo#sitemaps-and-robots-txt-files)。

<!-- 对 SEO 没有帮助 -->
[点击这里](/zh/optimize/seo)了解更多。

查找孤立页面： 没有内部链接指向的页面是孤立页面。搜索引擎不太可能发现和排名那些没有从任何地方链接到的页面。每月审查你的导航有助于发现这些页面。

创建主题集群： 将相关页面通过链接组合在一起。入门页面应该链接到身份验证参考，身份验证参考链接到 API 密钥页面，API 密钥页面再链接回概述页面。这向搜索引擎表明这些页面涵盖了一个连贯的主题。

替代文本同时服务于无障碍访问和 SEO。搜索引擎无法解读图片，因此替代文本是图片内容为页面相关性信号做出贡献的方式。

编写在上下文中描述图片内容的替代文本：

<!-- 具体且描述性 -->
![API 身份验证流程，展示客户端、身份验证服务器和 API 之间的令牌交换](/images/auth-flow.png)

<!-- 过于笼统 -->
![图表](/images/auth-flow.png)

在替代文本中自然地包含相关关键词。不要添加与图片无关的关键词。

Mintlify 负责多项技术 SEO 基础工作：

• Sitemap 生成： sitemap.xml 会自动生成和更新。你可以直接将其提交到 Google Search Console 以加速索引。
• 语义化 HTML： Mintlify 使用正确的 HTML 结构渲染页面，包括标题层次结构和导航地标。
• 移动端优化： 文档默认具有响应式设计。
• Canonical URL： 自动生成 canonical 标签以防止重复内容问题。

对于需要手动配置的内容——全局 meta 标签、页面级覆盖、自定义 sitemap、索引规则——请参阅 SEO 配置参考。

搜索引擎将内容新鲜度作为排名信号，尤其是对于涵盖随时间变化的主题的页面（API 参考、配置指南、集成说明）。

实用的方法：

• 当你发布功能更新时，在同一个 pull request 中更新相应的文档
• 每季度审查高流量页面的准确性
• 发布前使用 mint broken-links 检查损坏的链接

过时的文档会在 SEO 之外产生第二个问题：如果用户通过搜索找到你的页面但信息是错误的，他们会对你的文档失去信任。

为你的文档域名设置 Google Search Console。它会向你展示：

• 展示次数和点击量： 哪些页面出现在搜索结果中以及用户点击它们的频率
• 平均排名： 你的页面在特定查询中的排名位置
• 查询： 驱动流量的确切搜索词，对发现新的优化机会很有用

每月检查并优先处理展示次数高但点击量低的页面（你的标题或描述不够吸引人）以及重要查询排名较低的页面（内容深度可能需要改进）。