通过URI包含内容的引用

include指令能够识别目标是否是一个URI，并且能够包含该URI引用的内容。这个例子展示了如何直接将一个GitHub仓库中的AsciiDoc文件包含到你的文档中。

Unresolved directive in include-uri.adoc - include::example$include.adoc[tag=uri]

出于安全考虑，默认情况下*不启用此功能*。要允许从URI读取内容，您必须通过以下方式启用URI读取权限：

  1. 在`SERVER`模式或以下模式中运行Asciidoctor

  2. 从CLI或API安全地设置`allow-uri-read`属性

这是一个例子，展示了如何从控制台运行Asciidoctor，以便它能从URI读取内容：

$ asciidoctor -a allow-uri-read filename.adoc

记住，当从命令行运行时，Asciidoctor 默认以 UNSAFE 模式执行。

这是一个示例，展示了如何从API运行Asciidoctor，以便它可以从URI读取内容：

Asciidoctor.convert_file 'filename.adoc', safe: :safe, attributes: { 'allow-uri-read' => '' }
Warning
 从外部源包含内容存在一定的风险，包括将恶意行为引入到您的文档中的潜在风险。因为 allow-uri-read 是一个潜在的危险特性，所以当安全模式是 SECURE 或更高时，它会被强制禁用。
URI与URL的比较

URI代表统一资源标识符（Uniform Resource Identifier）。当我们谈论URI时，我们通常指的是URL，即统一资源定位符。URL只是一个指向网络上某个资源的URI，或者说是网址。

就Asciidoctor而言，所有的URI都有相同的限制，无论它实际上是本地的还是远程的，也无论它指向的是网络地址（http或https前缀）、FTP地址（ftp前缀）还是其他某种寻址方案。

本节描述的相同限制适用于嵌入从URI引用的图像，例如当设置`data-uri`时或者使用Asciidoctor PDF转换为PDF时。

缓存URI内容

从URI读取内容显然比从本地文件读取要慢得多。

Asciidoctor提供了一种方式，用于缓存从URI读取的内容，这是非常推荐的做法。

要启用内置缓存，你必须：

  1. 安装 open-uri-cached 宝石（gem）。

  2. 在文档中设置`cache-uri`属性。

当这两个条件得到满足时，Asciidoctor 会根据 HTTP 缓存建议 缓存从 URI 读取的内容。