URLs

在本页面上，您将学到：

  • 何时应该使用URL而不是交叉引用。

  • 如何创建带有和不带有链接文本的链接。

  • 如何转义URL。

  • 如何处理复杂的URL。

URL还是交叉引用？

当您需要创建到外部URL的链接时，请使用AsciiDoc的URL语法。外部URL是指您的Antora管道未构建为文档站点的网页链接。

当您想要链接到文档站点的页面、图片或附件时，请使用AsciiDoc xref宏和资源的资源ID。

URL语法
原始URL语法

与其他文档编写人员在chat.antora.org交谈。

以官方方案开头的链接，如https、ftp、mailto等，处理时会自动转换为超链接。这是原始URL语法的结果。

与其他文档编写人员在chat.antora.org交谈。

[]）括起文本。

示例1.带有链接文本语法的URL 
需要帮助吗？
访问https://chat.antora.org[Antora聊天室]。

示例1的结果如下所示。

需要帮助吗？访问Antora聊天室。

转义URL

当您想要显示URL但不希望其处于活动状态时，可以通过在其前面加上反斜杠（\）来转义它。

示例2.转义语法 
此URL显示为\https://gitlab.com，但不可点击。

示例2的结果如下所示。

此URL显示为https://gitlab.com，但不可点击。

故障排除URL

当URL包含下划线（_）或插入符（^）等字符时，可能无法正确显示，因为这些字符会被解释为文本格式标记。

  • 选项1：为URL创建自定义属性。

  • 选项2：使用内联传递宏并启用macros。

为URL创建属性

让我们为复杂的URL创建一个属性。为URL创建属性也是当URL很长时的一个好策略；它使源文本对于作者和编辑人员保持整洁。

示例3.自定义AsciiDoc属性语法 
= 页面标题
:url-peak: https://www.google.com/maps/place/Antora+Peak/@38.3249976,-106.2355882,14z/data=!3m1!4b1!4m5!3m4!1s0x871572433f469bd7:0xd2bdf15e615cd269!8m2!3d38.3249994!4d-106.2180786!5m1!1e4 (1)

{url-peak}[此URL]很复杂，但页面属性拯救了我们！ (2)
1 在源文件的标题中创建一个属性，赋予其名称，然后将URL分配给它。
2 当您想要在文本中创建指向该URL的链接时，使用属性（即引用该属性），就像您将使用URL一样。

示例3的结果如下所示。

此URL很复杂，但页面属性拯救了我们！

使用传递宏

 

pass:macros[URL放在这些括号之间]
示例4.带有宏替换语法的传递宏 
有人想和我一起攀登这座13er吗？（pass:macros[https://www.14ers.com/13ers/peak.php?peakkey=4740]）

示例4的结果如下所示。

有人想和我一起攀登这座13er吗？（www.14ers.com/13ers/peak.php?peakkey=4740）

AsciiDoc和Asciidoctor资源