merge PR #3880

resolves #3861 import Asciidoctor docs from asciidoctor.org/docs

1 files changed, 52 insertions, 0 deletions

diff --git a/docs/modules/extensions/pages/include-processor.adoc b/docs/modules/extensions/pages/include-processor.adoc
new file mode 100644
index 00000000..ee1a220a
--- /dev/null
+++ b/docs/modules/extensions/pages/include-processor.adoc
@@ -0,0 +1,52 @@
+= Include Processor Extension Example
+:navtitle: Include Processor
+
+Purpose::
+Include a file from a URI.
+
+TIP: Asciidoctor supports including content from a URI out of the box if you set the `allow-uri-read` attribute (not available if the safe mode is `secure`).
+
+== sample-with-uri-include.adoc
+
+[source,asciidoc]
+....
+:source-highlighter: coderay
+
+.Gemfile
+[source,ruby]
+----
+\include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
+----
+....
+
+== UriIncludeProcessor
+
+[source,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require 'open-uri'
+
+class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
+  def handles? target
+    (target.start_with? 'http://') or (target.start_with? 'https://')
+  end
+
+  def process doc, reader, target, attributes
+    content = (open target).readlines
+    reader.push_include content, target, target, 1, attributes
+    reader
+  end
+end
+----
+
+== Usage
+
+[source,ruby]
+----
+Asciidoctor::Extensions.register do
+  include_processor UriIncludeProcessor
+end
+
+Asciidoctor.convert_file 'sample-with-uri-include.adoc', safe: :safe
+----