## 链接

技术文档中的链接将用户引导至同一文档中的其他标题、其他相邻文档或外部站点。本节主要介绍在使用 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 效果，比如：[贡献者名单](https://github.com/yikeke/zh-style-guide/graphs/contributors)。

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