Include Content by URI

Reference include content by URI

The include directive recognizes when the target is a URI and can include the content referenced by that URI. This example demonstrates how to include an AsciiDoc file from a GitHub repository directly into your document.

include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/main/README.adoc[]

For security reasons, this capability is not enabled by default. To allow content to be read from a URI, you must enable the URI read permission by:

  1. running Asciidoctor in SERVER mode or less and

  2. setting the allow-uri-read attribute securely from the CLI or API

Here’s an example that shows how to run Asciidoctor from the console so it can read content from a URI:

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

Remember that Asciidoctor executes in UNSAFE mode by default when run from the command line.

Here’s an example that shows how to run Asciidoctor from the API so it can read content from a URI:

Asciidoctor.convert_file 'filename.adoc', safe: :safe, attributes: { 'allow-uri-read' => '' }
Including content from sources outside your control carries certain risks, including the potential to introduce malicious behavior into your documentation. Because allow-uri-read is a potentially dangerous feature, it is forcefully disabled when the safe mode is SECURE or higher.
URI vs URL

URI stands for Uniform Resource Identifier. When we talk about a URI, we’re usually talking about a URL, or Uniform Resource Locator. A URL is simply a URI that points to a resource over a network, or web address.

As far as Asciidoctor is concerned, all URIs share the same restriction, whether or not it’s actually local or remote, or whether it points to a web address (http or https prefix), FTP address (ftp prefix), or some other addressing scheme.

The same restriction described in this section applies when embedding an image referenced from a URI, such as when data-uri is set or when converting to PDF using Asciidoctor PDF.

Caching URI content

Reading content from a URI is obviously much slower than reading it from a local file.

Asciidoctor provides a way for the content read from a URI to be cached, which is highly recommended.

To enable the built-in cache, you must:

  1. Install the open-uri-cached gem.

  2. Set the cache-uri attribute in the document.

When these two conditions are satisfied, Asciidoctor caches content read from a URI according the to HTTP caching recommendations.