You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
64 lines
2.6 KiB
64 lines
2.6 KiB
4 years ago
|
////
|
||
|
|
=== Include content from a URI
|
||
|
|
|
||
|
|
This content is included in the user manual
|
||
|
|
////
|
||
|
|
|
||
|
|
The include directive recognizes when the target is a URI and can include the content referenced by that URI.
|
||
|
|
|
||
|
|
.Including content from a URI
|
||
|
|
====
|
||
|
|
This example demonstrates how to include an AsciiDoc file from a GitHub repo directly into your document.
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-include.adoc[tag=uri]
|
||
|
|
----
|
||
|
|
====
|
||
|
|
|
||
|
|
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:
|
||
|
|
|
||
|
|
. running Asciidoctor in `SERVER` mode or less and
|
||
|
|
. setting the `allow-uri-read` attribute securely (i.e., 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 SAFE 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:
|
||
|
|
|
||
|
|
[source,ruby]
|
||
|
|
----
|
||
|
|
Asciidoctor.convert_file 'filename.adoc', safe: :safe, attributes: { 'allow-uri-read' => '' }
|
||
|
|
----
|
||
|
|
|
||
|
|
WARNING: 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 https://en.wikipedia.org/wiki/Uniform_Resource_Identifier[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:
|
||
|
|
|
||
|
|
. Install the `open-uri-cached` gem.
|
||
|
|
. Set the `cache-uri` attribute in the document.
|
||
|
|
|
||
|
|
When these two conditions are satisfied, Asciidoctor caches content read from a URI according the to {uri-http}[HTTP caching recommendations].
|