如何在文档中使用链接

本文介绍如何使用 Microsoft Learn 中托管的页面中的超链接。 通过几种不同的约定，便可轻松地将链接添加到 markdown。 链接将用户指向相同页面中的内容、其他相邻页面或外部站点和 URL。

Microsoft Learn 后端使用 Open Publishing Services (OPS) ，它支持通过 Markdig 分析引擎分析符合 CommonMark 的 markdown。 Markdown 风格大多与 GitHub Flavored Markdown (GFM) 兼容，因为大多数 docs 存储在 GitHub 中，并可以在 GitHub 中进行编辑。 通过 Markdown 扩展添加一些功能。

重要

只要目标支持（绝大多数都应支持），所有链接均必须是安全的（https 与 http）。

链接文本中使用的关键字应反映相关内容。 换言之，它们应为一般中文关键字或所链接到的页面的标题。

重要

请勿使用“单击此处”作为链接文本。 这不利于搜索引擎优化，也不能充分地描述目标网页。

正确：

For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

不正确：

For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

发布系统支持两种类型的超链接：URL 和文件链接。

URL 链接可以是相对于 https://learn.microsoft.com 根的 URL 路径，也可以是包含完整 URL 语法（例如 https://github.com/MicrosoftDocs/PowerShell-Docs）的绝对 URL。

文件链接用于在 docset 中从一篇文章链接到另一篇文章。

所有文件路径都使用正斜杠 (/) 字符，而不是反斜杠字符。

一篇文章链接到同一目录中的另一篇文章：

[link text](article-name.md)

一篇文章链接到当前目录的父目录中的一篇文章：

[link text](../article-name.md)

一篇文章链接到当前目录的子目录中的一篇文章：

[link text](directory/article-name.md)

一篇文章链接到当前目录的父目录的子目录中的一篇文章：

[link text](../directory/article-name.md)

某些项目由 .yml 和 .md 文件组成，其中 .yml 文件包含元数据， .md 而 包含内容。 在这种情况下，请链接到 .yml 文件：

[link text](../directory/article-name.yml) (不[link text](../directory/article-name-content.md))

注意

上述示例中均未在链接中使用 ~/。 若要链接到以存储库根目录开头的绝对路径，请启用包含 / 的链接。 如果包含 ~/，当在 GitHub 上导航源存储库时会生成无效的链接。 使路径以 / 开头便可有效解决此问题。

在 Microsoft Learn 上发布的内容具有以下 URL 结构：

https://learn.microsoft.com///[]/[]/[?view=]

示例：

提示

大多数情况下，同一 docset 中的文章具有相同的 URL 片段。 例如：

对于当前文件中标题的书签链接，请使用哈希符号，后跟标题的小写字词。 删除标题中的标点符号并将空格替换为短划线：

若要链接到另一篇文章中的某个书签标题，请使用文件相对或站点相对链接以及井号，后跟标题内容。 删除标题中的标点符号并将空格替换为短划线：

还可以从 URL 复制书签链接。 若要查找 URL，请将鼠标悬停在 Microsoft Learn 上的标题行上。 应该会看到一个链接图标出现：

单击链接图标，然后从 URL 复制书签定位文本（即哈希后的部分）。

注意

Learn Markdown 扩展还具有帮助创建链接的工具。

使用 HTML 标记添加显式定位标记链接并非必需，也不推荐使用，但在中心和登录页面中除外。 请改为使用自动生成的书签，如书签链接中所述。 对于中心和登录页面，声明如下所示的定位标记：

或

以下链接到定位标记：

注意

定位文本必须始终为小写，且不包含空格。

XRef 链接是链接到 API 的推荐方式，因为它们在生成时经过验证。 若要链接到当前文档集或其他文档集中自动生成的 API 参考页，请使用具有类型或成员的唯一 ID (UID) 的 XRef 链接。

提示

可以使用 适用于 VS Code 的 Learn Markdown 扩展 (Learn 创作包) 的一部分来插入显示在 .NET API 浏览器中的 .NET XRref 链接。

通过在 .NET API 浏览器或 Windows UWP 搜索框中键入所有或部分全名，检查要链接到的 API 是否在 Microsoft Learn 上发布。 如果未看到任何结果显示，则类型尚未显示在 Microsoft Learn 上。

可使用下列某一语法：

自动链接：

默认情况下，链接文本仅显示成员名称或类型名称。 可选 displayProperty=nameWithType 查询参数生成完全限定的链接文本，即类型 namespace.type，以及类型成员（包括枚举类型成员）type.member。

Markdown 样式链接：

如果要自定义显示的链接文本，请使用适用于 XRef 的 Markdown 样式链接。

示例：

显示为 String

显示为 System.String

[String class](xref:System.String) 显示为字符串类。

displayProperty=fullName 查询参数的工作方式与类的 displayProperty=nameWithType 相同。 也就是说，链接文本将成为 namespace.classname。 但是，对于成员，链接文本显示为 namespace.classname.membername，这可能不可取。

注意

UID 是区分大小写的。 例如， 会正确解析，但 不会正确解析。

增量生成仅生成已更改或受更改影响的文件。 如果你看到有关无效 XREF 链接的生成警告，但该链接实际上有效，这可能是因为生成是增量的。 导致警告的文件未更改，因此未生成该文件，过去的警告被重播。 文件更改或你触发完整生成（你可以在 ops.microsoft.com 上启动完整生成）时，警告将消失。 这是增量生成的一个缺点，因为 DocFX 无法检测到 XREF 服务中的数据更新。

UID 通常是完全限定的类或成员名称。 确定 UID 的方法至少有两种：

右键单击类型或成员的 Microsoft Learn 页面，选择“查看源”，然后复制 ms.assetid的内容值：

通过将类型的部分或全部名称追加到 URL 中，使用自动完成网站。 例如，在浏览器的地址栏中输入 https://xref.docs.microsoft.com/autocomplete?text=Writeline 会显示所有类型和方法，这些类型和方法的名称中包含 Writeline 及其 UID。

若要测试你是否具有正确的 UID，请将以下 URL 中的 System.String 替换为你的 UID，然后将其粘贴到浏览器的地址栏中：

https://xref.docs.microsoft.com/query?uid=System.String

提示

URL 中的 UID 区分大小写，如果要检查方法重载 UID，则不要在参数类型之间包含空格。

如果看到以下类似内容，则你具有正确的 UID：

如果只是看到页面上显示 [] ，则 UID 错误。

UID 中的特殊字符需要进行 HTML 编码，如下所示：

查看百分数代码的完整列表。

编码示例：

System.Threading.Tasks.Task`1 编码为 System.Threading.Tasks.Task%601（请参阅泛型类型部分）

System.Exception.#ctor 编码为 System.Exception.%23ctor

System.Object.Equals* 编码为 System.Object.Equals%2A

泛型类型是诸如 System.Collections.Generic.List 这样的类型。 如果在 .NET API 浏览器中浏览到此类型并查看其 URL，你会看到 在 URL 中编写为 -1，这实际上表示 `1：

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

若要链接到泛型类型（如 List），将 ` 反引号符号编码为 %60，如以下示例中所示：

若要链接到方法，可以通过在方法名称后添加星号 (*) 链接到常规方法页面，或链接到特定重载。 例如，如果要链接到没有特定参数类型的 方法，请使用“常规”页面。 星号字符编码为 %2A。 例如：

链接到 Object.Equals

要链接到特定重载，请在方法名称后添加括号，并包含每个参数的完整类型名称。 请勿在类型名称之间放置空格字符，否则链接将无法正常工作。 例如：

链接到 Object.Equals(Object, Object)

包含文件位于另一个目录中，因此，必须使用较长的相对路径。 若要从包含文件链接到某一篇文章，请使用以下格式：

提示

适用于 Visual Studio Code 的 Learn 创作包扩展可帮助你正确插入相对链接和书签，而无需找出路径。

选择器是导航组件，以下拉列表的形式在文档文章中显示。 当读者选择下拉列表中的值时，浏览器将打开所选文章。 通常情况下，选择器列表包含密切相关文章的链接，例如，多种编程语言中的相同主题，或密切相关的文章系列。

如果你的选择器嵌入在包含文件中，则使用以下链接结构：

可以使用引用样式链接使源内容更易于读取。 引用样式链接使用简化的语法替代内联链接语法，以便将长 URL 移动到文章末尾。 下面是 Daring Fireball 的示例：

内联文本：

文章末尾部分的链接引用：

请务必在链接前的冒号后加入空格。 链接到其他技术文章时，如果忘记加入空格，链接会在发布文章中被破坏。

若要链接到另一个 Microsoft 属性（例如定价页、SLA 页或其他非文档文章的页面），请使用绝对 URL，但要忽略区域设置。 这样做是为了使链接在 GitHub 和显示链接的网站上正常工作：

为了实现最佳用户体验，最好尽量减少将用户定向到另一个网站的次数。 因此，如果确实需要，可在以下信息基础上实现到第三方网站的任何链接：