merge PR #3880

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

1 files changed, 68 insertions, 0 deletions

diff --git a/docs/modules/extensions/pages/preprocessor.adoc b/docs/modules/extensions/pages/preprocessor.adoc
new file mode 100644
index 00000000..d1cc95f1
--- /dev/null
+++ b/docs/modules/extensions/pages/preprocessor.adoc
@@ -0,0 +1,68 @@
+= Preprocessor Extension Example
+:navtitle: Preprocessor
+
+Purpose::
+Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct.
+
+== sample-with-front-matter.adoc
+
+[source,asciidoc]
+----
+tags: [announcement, website]
+---
+= Document Title
+
+content
+
+[subs=+attributes]
+.Captured front matter
+....
+---
+{front-matter}
+---
+....
+----
+
+== FrontMatterPreprocessor
+
+[source,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
+  def process document, reader
+    lines = reader.lines # get raw lines
+    return reader if lines.empty?
+    front_matter = []
+    if lines.first.chomp == '---'
+      original_lines = lines.dup
+      lines.shift
+      while !lines.empty? && lines.first.chomp != '---'
+        front_matter << lines.shift
+      end
+
+      if (first = lines.first).nil? || first.chomp != '---'
+        lines = original_lines
+      else
+        lines.shift
+        document.attributes['front-matter'] = front_matter.join.chomp
+        # advance the reader by the number of lines taken
+        (front_matter.length + 2).times { reader.advance }
+      end
+    end
+    reader
+  end
+end
+----
+
+== Usage
+
+[source,ruby]
+----
+Asciidoctor::Extensions.register do
+  preprocessor FrontMatterPreprocessor
+end
+
+Asciidoctor.convert_file 'sample-with-front-matter.adoc', safe: :safe
+----