链接宏是在AsciiDoc中创建链接的最明确的方法。只有当自动链接和URL宏的行为不足时才需要使用。本页涵盖了链接宏的结构，何时需要它以及如何使用它。
解剖学
链接宏是一种内联宏。像其他内联宏一样，其语法遵循宏名称和目标之间用冒号分隔，然后跟随一个用方括号括起来的属性列表的熟悉模式。
link:<target>[<attrlist>]<target>` 成为链接的目标。除非检测到命名属性，否则 <attrlist> 是链接文本。参阅 链接宏属性列表 以了解如何解析 <attrlist>。
就像所有内联宏一样，链接宏可以通过前面加上反斜杠（\）来转义。
链接到一个相对路径的文件
如果您想要链接到一个相对于当前文档的非AsciiDoc文件，请在文件名前使用`link`宏。
|
Tip
|
要链接到一个相对路径的AsciiDoc文件，请使用xref宏。 |
这是一个示例，演示了如何使用链接宏来链接到一个相对文件路径。
Unresolved directive in link-macro.adoc - include::example$url.adoc[tag=link]AsciiDoc处理器将创建一个链接，文本为“获取报告”（Get Report），指向_report.pdf_，即使目标不是一个URL。
如果目标文件是一个HTML文件，并且你想直接链接到该文档内的一个锚点，请在文件名后附加一个井号（#）再跟上锚点的名称：
Unresolved directive in link-macro.adoc - include::example$url.adoc[tag=hash]请注意，当链接到一个相对文件时，即使它是一个HTML文件，也需要链接文本。
何时使用链接宏
由于AsciiDoc提供了自动链接和URL宏，因此链接宏通常是不必要的。以下是少数需要链接宏的情况：
-
目标不是URL（例如，是一个相对路径）
-
目标必须被包含在一个直通方式中以逃避具有特殊含义的字符。
-
URL宏不受空格、括号或引号的限制。
-
目标是一个URL，它不以AsciiDoc识别的协议开头。
最常见的情况是目标不是一个URL。例如，你会使用链接宏来创建一个指向相对路径的链接。
链接：report.pdf[获取报告]|
Tip
|
如果相对路径是另一个AsciiDoc文件，你应该使用xref宏来替代。 |
您可能还会发现，在链接宏的目标中不允许使用空格，至少在AsciiDoc源码中是这样的。目标中的空格字符会阻止解析器识别宏。因此，必须对其进行转义或编码。以下是三种方法：
link:pass:[My Documents/report.pdf][获取报告]link:My Documents/report.pdf[获取报告]link:My%20Documents/report.pdf[Get Report]转义或编码空格确保空格不会阻止链接宏被识别。使用URL编码的缺点是它会在自动生成的链接文本中可见，因为浏览器不会在那个位置解码它。在这种情况下，字符引用是更好的选择。
在链接目标中也不允许使用其他字符，例如冒号。您可以采用相同的技术对这些字符进行转义。
link:Avengers%3A%20Endgame.html[]另一个常见的情况是当你需要使用穿透功能来转义具有特殊含义的字符时。在这种情况下，AsciiDoc处理程序将无法识别目标为URL，因此需要使用链接宏。例如，当URL包含重复的下划线字符时。
link:++https://example.org/now_this__link_works.html++[]一个类似的情况是，当URL宏没有被空格、括号或引号所包围时。在这种情况下，需要使用链接宏前缀来提高其优先级，以便能够识别该宏。
|link:https://asciidoctor.org[]|最后，如果AsciiDoc没有将目标识别为URL，那么就需要使用链接宏。例如，您可能会使用链接宏来创建一个文件链接。
link:file:///home/username[Your files]决定性的话
一般规则是，只有当目标不是URL时，才应该在目标前面加上`link:`宏前缀。否则，前缀只会增加冗余。