跳转到主要内容
搜索引擎是用户查找文档最可靠的途径之一。当有人搜索”如何使用 [你的产品] 设置身份验证”时，优化良好的文档会将你的内容置于搜索结果的顶部，而不是 Stack Overflow 帖子或竞争对手的页面。 本指南涵盖了对文档 SEO 影响最大的技巧，从编写更好的页面标题到构建可维护的内部链接策略。

​
编写能获得排名的页面标题和描述

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

​
标题（50-60 个字符）

编写与用户搜索方式匹配的标题，而不是产品界面的标签。“身份验证”是一个产品标签。“如何对 API 请求进行身份验证”是一个搜索查询。
  • 匹配用户意图：在适当的地方使用”如何”、“指南”或”参考”
  • 将主要关键词放在标题靠前的位置
  • 确保每个标题都是唯一的——重复的标题会让搜索引擎感到困惑

​
描述（130-160 个字符）

描述出现在搜索结果中页面标题的下方。好的描述即使在排名相同的情况下也能提高点击率。
  • 概述用户将完成什么，而不仅仅是页面涵盖什么
  • 自然地包含主要关键词
  • 使用主动语态：“了解如何配置……”而不是”本页介绍……”
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, 谨慎使用)
将标题写成问题或意图短语。 比较：
较弱的标题更好的标题
身份验证身份验证的工作原理
速率限制了解 API 速率限制
配置如何配置你的集成
以问题形式编写的标题更有可能出现在 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

Mintlify 负责多项技术 SEO 基础工作：
  • Sitemap 生成： sitemap.xml 会自动生成和更新。你可以直接将其提交到 Google Search Console 以加速索引。
  • 语义化 HTML： 页面使用正确的 HTML 结构渲染，包括标题层次结构和导航地标。
  • 移动端优化： 文档默认具有响应式设计。
  • Canonical URL： 自动生成 canonical 标签以防止重复内容问题。
对于需要手动配置的内容——全局 meta 标签、页面级覆盖、自定义 sitemap、索引规则——请参阅 SEO 配置参考。

​
保持文档更新

搜索引擎将内容新鲜度作为排名信号，尤其是对于涵盖随时间变化的主题的页面（API 参考、配置指南、集成说明）。 实用的方法：
  • 当你发布功能更新时，在同一个 pull request 中更新相应的文档
  • 每季度审查高流量页面的准确性
  • 发布前使用 mint broken-links 检查损坏的链接
使用 workflows 来自动化 SEO 维护任务。
过时的文档会在 SEO 之外产生第二个问题：如果用户通过搜索找到你的页面但信息是错误的，他们会对你的文档失去信任。

​
监控你的搜索表现

为你的文档域名设置 Google Search Console。它会向你展示：
  • 展示次数和点击量： 哪些页面出现在搜索结果中以及用户点击它们的频率
  • 平均排名： 你的页面在特定查询中的排名位置
  • 查询： 驱动流量的确切搜索词，对发现新的优化机会很有用
每月检查并优先处理展示次数高但点击量低的页面（你的标题或描述不够吸引人）以及重要查询排名较低的页面（内容深度可能需要改进）。

​
常见问题

没有通用的理想长度。页面应该足够长以全面涵盖主题，又足够短以保持专注。入门指南可能是 800 个单词。详细的 API 参考可能是 3,000 个单词。重要的是用户能够从页面上完成他们的目标——如果他们需要离开去寻找额外信息，页面可能太单薄了。一般来说，少于 300 个单词的页面很难在竞争性查询中获得排名，因为它们无法展示主题深度。
核心原则是相同的。相关的标题、结构良好的内容和内部链接都很重要。但文档有一些独特的优势。文档页面通常针对高度特定的长尾查询（“如何使用 [产品] 配置 OAuth”），竞争比一般博客主题少。当开发者在 Stack Overflow 回答、GitHub issue 和社区论坛中分享文档时，它们也会自然地积累链接。专注于特异性和准确性，而非数量。
在 Google Search Console 中，前往左侧边栏的 Sitemaps 并输入你的 sitemap URL。对于 Mintlify 文档，你的 sitemap 位于 https://your-docs-domain.com/sitemap.xml。提交 sitemap 并不能保证立即索引，但它可以加速发现并帮助 Google 了解你的网站结构。
每当产品发生变化时就更新文档——准确性是最重要的信号。具体到 SEO，超过一年未更新的页面可能需要审查，以添加缺失的信息、更新示例和扩展单薄的部分。使用 Google Search Console 来确定优先级：流量下降或排名下降的页面是需要刷新的候选对象。
SEO（Search Engine Optimization，搜索引擎优化）专注于在 Google 和 Bing 等传统搜索引擎中获得排名。GEO（Generative Engine Optimization，生成式引擎优化）专注于被 ChatGPT、Perplexity 和 Google AI Overviews 等 AI 驱动工具引用。基本原理是重叠的——准确、结构良好的内容在两者中都表现出色——但 GEO 在针对 AI 解析的格式方面有一些额外的实践。详情请参阅 GEO 指南。
Mintlify 处理技术基础：sitemap 生成、语义化 HTML、canonical 标签、meta 标签生成和移动端优化。Mintlify 无法为你做的是编写更好的标题、进行关键词研究、建立内部链接或扩展单薄的内容——这些需要编辑决策。SEO 配置参考涵盖了你可以通过 docs.json 和页面 frontmatter 控制的所有内容。