链接

技术文档中的链接将用户引导至同一文档中的其他标题、其他相邻文档或外部站点。本节主要介绍在使用 Markdown 语言编写的技术文档中使用链接建议遵循的规范。

Markdown 中的链接格式示例：

• 链至同一文档中的其他标题：[产品架构](#产品架构)
• 链至其他相邻文档：[产品架构](../docs/architecture.md)
• 链至外部站点：[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)

链接的描述

Markdown 链接中方括号 [] 里的内容为该链接的描述性文本。链接的描述需要符合以下规范。

• 链接描述必须能概括所链文档或页面的大致内容，这有利于搜索引擎优化。例如，链接描述可以是所链页面的标题。

  • 【错误示例】

    • 详情参见 [trouble-shooting.md](trouble-shooting.md)
    • 详情请点击[这里](trouble-shooting.md)

  • 【正确示例】

    • 关于以上配置项的更多细节，参见[功能配置集](#功能配置集)的相关配置项。
    • 详情参见[故障诊断文档](trouble-shooting.md)。

• 同类型的链接描述应尽量统一风格。例如：同一文档内不宜多次出现“详情参见”、“详情参阅”、“具体见”、“具体请见”等表达相同意思的不同描述。

链接的路径

Markdown 链接中圆括号 () 里的内容即为该链接的路径。链接的路径需要符合以下规范。

• 如链至其他相邻文档，且链接的文档篇幅较长，建议链接至锚点。链接至锚点即链接至某级标题处。Markdown 支持在链接路径的文件名后加“#标题名称”，即可以链接至该文件的特定标题处。

  • 【示例】[配置文件](trouble-shooting.md#配置文件)这个链接将链至 trouble-shooting.md 文件的“配置文件”标题下。

• 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。

• 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。

  外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。

• 如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点。

  由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。

  • 【示例一】如果前端能力足够，可以在外链后加上通用的外链 icon 效果，比如：贡献者名单。

  • 【示例二】在 Markdown 中，可以简单在链接的路径后加上 "点击前往外部站点" 或者 "点击前往 XXX 网站"等信息，如 [链接的描述](链接的路径 "前往外部链接的提示")，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。