jekyll-asciidoc 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70e3a563b71258539aec7af2a1b3f54f23ee28e2
-  data.tar.gz: 92794e6be1f68a919b7f668c38420c37cba94194
+  metadata.gz: 48f6d28bbd931f1d823e06625ad68b9314cf8836
+  data.tar.gz: c59995e13e47e147624ec578d4c42cf5d187953f
 SHA512:
-  metadata.gz: 51b0b989d383316e56321c136da7a39fd7ff6356b5c22751a21803427d43b10f120395fd4660fd1e858eb0f2b01006fff0be13d552f3fb6d0577e480ba2ea0ab
-  data.tar.gz: 9cc3b1abf6401faa525fa5073274b5d7de840608cf894d4c5703eb53913afac970aac15c25bc3ea26f4f05920732523ea41317a811555d5542b3486bc93a99ba
+  metadata.gz: f97b51d72a92abc00d2bed80fc561ef74bb26e9022be6204af97dca38830f38bf09f54bd18fc99920e4cacbc171f86e0f238a322f7ec291f3aa0cf56752e5dd2
+  data.tar.gz: e1905e712312e6d108de8f79ad69717477d71f33f62b4baf653ca86f7988f80b203172b8e1027070a5a27b20cd23190a052996cc44a4dce3263480963b0f2551

data/{LICENSE → LICENSE.adoc}

@@ -1,6 +1,6 @@
-The MIT License
-
-Copyright (C) 2013 Dan Allen
+.The MIT License
+....
+Copyright (C) 2013-2016 Dan Allen and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+....

data/README.adoc

@@ -1,5 +1,6 @@
 = Jekyll AsciiDoc Plugin (powered by Asciidoctor)
-Paul Rayner <https://github.com/paulrayner[@paulrayner]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Paul Rayner <https://github.com/paulrayner[@paulrayner]>
+v2.0.0, 2016-07-02
 // Settings:
 :idprefix:
 :idseparator: -
@@ -18,115 +19,188 @@ ifdef::env-github[]
 :tip-caption: :bulb:
 :warning-caption: :warning:
 endif::[]
-
-A plugin for http://jekyllrb.com[Jekyll] that converts http://asciidoc.org[AsciiDoc] files in your site source to HTML pages using http://asciidoctor.org[Asciidoctor].
+// Aliases:
+:path-config: pass:q[[path]___config.yml__]
+:conum-guard: {sp}
+ifndef::icons[:conum-guard: {sp}#{sp}]
+// URIs:
+:uri-repo: https://github.com/asciidoctor/jekyll-asciidoc
+:uri-issues: {uri-repo}/issues
+:uri-search-issues: {uri-repo}/search?type=Issues
+:uri-chat: https://gitter.im/asciidoctor/asciidoctor
+:uri-ci: https://travis-ci.org/asciidoctor/jekyll-asciidoc
+:uri-gem: http://rubygems.org/gems/jekyll-asciidoc
+:uri-gem-asciidoctor: http://rubygems.org/gems/asciidoctor
+:uri-asciidoc: http://asciidoc.org
+:uri-asciidoctor: http://asciidoctor.org
+:uri-asciidoctor-backends: https://github.com/asciidoctor/asciidoctor-backends
+:uri-asciidoctor-docs: {uri-asciidoctor}/docs
+:uri-asciidoctor-diagram: {uri-asciidoctor-docs}/asciidoctor-diagram
+:uri-asciidoctor-discuss: http://discuss.asciidoctor.org
+:uri-asciidoctor-manual: {uri-asciidoctor-docs}/user-manual
+:uri-asciidoc-practices: {uri-asciidoctor-docs}/asciidoc-recommended-practices
+:uri-jaq: https://github.com/asciidoctor/jekyll-asciidoc-quickstart
+:uri-jekyll: https://jekyllrb.com
+:uri-jekyll-docs: {uri-jekyll}/docs
+:uri-jekyll-discuss: https://talk.jekyllrb.com
+:uri-front-matter: {uri-jekyll-docs}/frontmatter
+:uri-liquid-templates: {uri-jekyll-docs}/templates
+:uri-graphviz: http://www.graphviz.org
+:uri-tilt: https://github.com/rtomayko/tilt
+:uri-yaml: https://en.wikipedia.org/wiki/YAML
+:uri-guide-publish-gem: http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg
 
 ifdef::status[]
-image::https://img.shields.io/gem/v/jekyll-asciidoc.svg?label=gem%20version[Gem Version, link=https://rubygems.org/gems/jekyll-asciidoc]
+image:https://img.shields.io/gem/v/jekyll-asciidoc.svg?label=gem%20version[Gem Version, link={uri-gem}]
+image:https://img.shields.io/travis/asciidoctor/jekyll-asciidoc/master.svg[Build Status (Travis CI), link={uri-ci}]
 endif::[]
 
+A plugin for {uri-jekyll}[Jekyll] (>= 2.3.0) that converts {uri-asciidoc}[AsciiDoc] source files in your site to HTML pages using {uri-asciidoctor}[Asciidoctor].
+
 == Overview
 
 The plugin consists of three extensions:
 
-`Jekyll::Converters::AsciiDocConverter`::
-  Converts AsciiDoc files to HTML
-`Jekyll::Generators::AsciiDocPreprocessor`::
-  Promotes select AsciiDoc attributes to Jekyll front matter (e.g., title, author, page-layout)
-`Jekyll::Filters.asciidocify`::
-  A Liquid filter for converting AsciiDoc content to HTML using the AsciiDocConverter
-
-These extensions are loaded automatically when the jekyll-asciidoc is required.
+Converter -- `Jekyll::AsciiDoc::Converter`::
+Converts AsciiDoc files to HTML pages.
+This plugin currently uses Asciidoctor to convert AsciiDoc content.
 
-== Installation
-
-The plugin depends on the http://rubygems.org/gems/asciidoctor[asciidoctor] gem.
-You can install the gem using:
+Generator -- `Jekyll::AsciiDoc::Integrator`::
+Promotes select AsciiDoc attributes (e.g., title, author, page-layout, page-*) to page variables (merged with the page variables defined in the front matter header).
 
- $ gem install asciidoctor
+Liquid Filter -- `asciidocify`::
+A Liquid filter that uses the converter from this plugin to convert AsciiDoc content to HTML.
 
-If you're using Bundler to manage the dependencies in your Jekyll project, instead add the asciidoctor gem to your [path]_Gemfile_ (beneath the jekyll gem):
+These extensions are registered automatically when the [app]*jekyll-asciidoc* gem is required.
 
-[source,ruby]
-----
-source 'https://rubygems.org'
+== Installation
 
-gem 'jekyll'
-gem 'asciidoctor'
-----
+This plugin is packaged as a gem named [app]*{uri-gem}[jekyll-asciidoc]* and published to RubyGems.org.
+The plugin depends on the [app]*{uri-gem-asciidoctor}[asciidoctor]* gem, which gets installed automatically.
 
-Then, run the Bundler install command:
+Your method of installation will depend on whether you use Bundler to manage the dependencies for your Jekyll project.
 
- $ bundle install
+=== Installation Using Bundler
 
-=== Installing a released version of the plugin
-
-Using Bundler::
-+
---
-Add the `jekyll-asciidoc` plugin gem to your [path]_Gemfile_
+If you're using Bundler to manage the dependencies for your project (as recommended), simply add the [app]*jekyll-asciidoc* gem to the `:jekyll_plugins` group in your [path]_Gemfile_:
 
 [source,ruby]
+----
 group :jekyll_plugins do
   gem 'jekyll-asciidoc'
 end
+----
 
-Then, run the Bundler command to install it:
+Then, run the `bundle` command from Bundler to install the gem:
 
- $ bundle install
---
+ $ bundle
 
-Without Bundler::
-+
---
-If you are not using Bundler for managing Jekyll then install gems manually
+=== Manual Installation
+
+If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually:
 
- $ gem install jekyll-asciidoc
+ $ [sudo] gem install jekyll-asciidoc
 
-And then, add the `jekyll-asciidoc` gem to the list of gems for Jekyll to load in your site's [path]_{empty}_config.yml_ file:
+NOTE: The `sudo` prefix is only required if you are installing gems into your system.
+To avoid this bad practice, we recommend using RVM (or another Ruby version manager), which sets up Ruby safely in your home directory.
+
+Then add the [app]*jekyll-asciidoc* gem to the list of gems for Jekyll to load in your site's {path-config} file:
 
 [source,yaml]
+----
 gems:
   - jekyll-asciidoc
---
-
-=== Installing development version of the plugin
-
-To install the development version of this plugin, use:
-
- $ rake install
+----
 
-An alternative--though not recommend--approach is to copy the file [path]_lib/jekyll-asciidoc.rb_ to the [path]_{empty}_plugins_ directory in the root of your site source.
+== Creating Pages
 
-NOTE: If the [path]_{empty}_plugins_ directory does not exist, you need to first create it.
+This plugin converts eligible AsciiDoc files located inside the source directory (by default, the project root) to HTML pages in the generated site.
+There are a few conditions that must be met in order for an AsciiDoc file to be eligible:
 
-== Creating pages
+. The file must have an AsciiDoc file extension (see <<configuration>>).
+. The name of the file must not begin with a dot (`.`) or an underscore (`_`).footnoteref:[excluded_files,Hidden files and folders are automatically excluded by Jekyll.]
+. The file must not be located in a folder whose name begins with a dot (`.`) or an underscore (`_`) (unless the folder is a designated collection, such as _posts).footnoteref:[excluded_files]
+. With the exception of posts, documents must begin with a {uri-front-matter}[front matter header] if using a version of this plugin < 2.0.0.
+Since version 2.0.0 of this plugin, the front matter header is always optional.
 
-To add a page composed in AsciiDoc, simply add an AsciiDoc file to the root of the project with an AsciiDoc file extension.
+Here's a sample AsciiDoc file that meets these criteria:
 
 .sample.adoc
-[listing]
-....
+[source,asciidoc]
+----
 ---
+layout: info
+permalink: /sample/
 ---
 = Sample Page
-:page-layout: page
-:permalink: /page/
+:uri-asciidoctor: http://asciidoctor.org
 
 This is a sample page composed in AsciiDoc.
-Jekyll converts it to HTML using http://asciidoctor.org[Asciidoctor].
+Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
 
 [source,ruby]
+puts "Hello, World!"
 ----
+
+Alternatively, you can define the page variables directly in the AsciiDoc header, which we recommend:
+
+.sample.adoc
+[source,asciidoc]
+----
+= Sample Page
+:page-layout: info
+:page-permalink: /sample/
+:uri-asciidoctor: http://asciidoctor.org
+
+This is a sample page composed in AsciiDoc.
+Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
+
+[source,ruby]
 puts "Hello, World!"
 ----
-....
 
-IMPORTANT: The AsciiDoc file must have a http://jekyllrb.com/docs/frontmatter/[YAML front matter] header or else it won't be recognized as a page.
-You can use an empty front matter header, as shown above, or you can define all your document metadata (e.g., document title) in the front matter instead of AsciiDoc attributes.
+AsciiDoc attributes defined in the document header whose names begin with ``page-``footnote:[The prefix used to label page attributes can be customized.] get promoted to page variables.
+The part of the name after the `page-` prefix is used as the entry's key (e.g., page-layout becomes layout) and the value is interpeted as {uri-yaml}[YAML] data (that which can be expressed in a single line).
 
-NOTE: AsciiDoc attributes defined in the document header whose names begin with `page-` are promoted to Jekyll front matter.
-The part of the name after the `page-` prefix is used as the key (e.g., page-layout becomes layout).
+The most commonly defined page variable is layout, which determines which template is used to wrap the generated content.
+Jekyll will look for a template file inside the [path]_{empty}_layouts_ folder whose root name matches the name of the layout.
+For example, if the layout variable has the value `info`, Jekyll looks for a layout template at the path [path]__layout/info.html_.
+
+If the layout is empty, the auto-selected layout layout is used (documented in the list below).
+If the layout is unset or `false`, the AsciiDoc processor will generate a standalone document.
+In this case, the page will appear like an HTML file generated by the AsciiDoc processor directly (with the option `header_footer: true`).
+If the layout is ~, no layout is applied.
+
+To review, here are the different ways to specify a layout using the AsciiDoc attribute page-layout:
+
+* `:page-layout: info` -- use the layout named `info` (e.g., [path]__layout/info.html_)
+* _not specified_, `:page-layout:` or `:page-layout: _auto` -- use the automatic layout (i.e., `page` for pages, `post` for posts, the singular form of the collection label for a document; if the auto-selected layout isn't available, the layout `default` is used)
+* `:!page-layout:` or `:page-layout: false` -- don't use a layout; instead, generate a standalone HTML document
+* `:page-layout: ~` -- don't use a layout (often results in an incomplete HTML file)
+
+In addition to page attributes defined explicitly, the following implicit AsciiDoc attributes are also promoted to page variables:
+
+* doctitle (i.e., the document title) (becomes title)
+* author
+* revdate (becomes date; value is converted to a DateTime object; only for posts)
+
+Unlike other content files, the {uri-liquid-templates}[Liquid template preprocessor] is not applied to AsciiDoc files by default (as of version 2.0.0 of this plugin).
+If you want the Liquid template preprocessor to be applied to an AsciiDoc file (prior to the content being passed to the AsciiDoc processor), you must enable it by setting the `liquid` page variable (shown here defined using a page attribute).
+
+[source,asciidoc]
+----
+:page-liquid:
+----
+
+IMPORTANT: AsciiDoc files may include a {uri-front-matter}[front matter header] for defining page variables.
+If present, the front matter header must be the very first character of the file.
+The front matter header won't be seen--and could distort conversion--if the front matter is preceded by whitespace or a Byte Order Mark (BOM).
+
+NOTE: As of version 2.0.0 of this plugin, you may exclude the front matter header, as shown in the second example above.
+Prior to version 2.0.0, you had to include at least an empty front matter header (except for posts).
+In these cases, you define all the page variables (e.g., layout) using AsciiDoc page attributes instead of in the front matter.
+You can also use a combination of both.
+When intermixed, the page attributes defined in the AsciiDoc header take precedence.
 
 You can now build your site using:
 
@@ -136,83 +210,325 @@ and preview it using:
 
  $ jekyll serve
 
-If you are using Bundler then use following commands to do the same
+If you're using Bundler, then prefix the commands with `bundle exec`, as in:
 
  $ bundle exec jekyll build
- $ bundle exec jekyll serve
+
+To see a report of all the files that are processed, add the `--verbose` flag:
+
+ $ jekyll build --verbose
+
+If an AsciiDoc file is not listed, then likely Jekyll did not find a {uri-front-matter}[front matter header].
 
 IMPORTANT: If you use the `--safe` option, the AsciiDoc plugin will not be activated.
 The `--safe` flag disables third-party plugins such as this one.
 
-== Configuration (optional)
+== Configuration
+
+This section describes the configuration options for this plugin, which are _optional_.
+
+You should at least assign an empty Hash as a default (e.g., `{}`) to the `asciidoc` and `asciidoctor` keys in {path-config}, respectively, if you don't plan on making any further customizations.
+
+[source,yaml]
+----
+asciidoc: {}
+asciidoctor: {}
+----
+
+Using these placeholder values is an optimization that prevents initialization from being performed more than once.
+
+=== AsciiDoc
+
+NOTE: Prior to version 2.0.0 of this plugin, the configuration keys in this section were defined as flat, top-level names (e.g., `asciidoc_ext`).
+These names are now deprecated, but still supported.
 
 By default, this plugin uses Asciidoctor to convert AsciiDoc files.
-Since Asciidoctor is the only option, the default setting is equivalent to the following configuration in [path]_{empty}_config.yml_:
+Since Asciidoctor is currently the only option, the default setting is equivalent to the following configuration in {path-config}:
 
 [source,yaml]
-asciidoc: asciidoctor
+----
+asciidoc:
+  processor: asciidoctor
+----
 
-To tell Jekyll which extensions to recognize as AsciiDoc files, add the following line to your [path]_{empty}_config.yml_:
+IMPORTANT: The `asciidoc` block should only appear _once_ inside {path-config}.
+If you define any other options that are documented in this section, you should append them to the `asciidoc` block.
+
+To tell Jekyll which file extensions to match as AsciiDoc files, append the `ext` option to the `asciidoc` block of your {path-config}:
 
 [source,yaml]
-asciidoc_ext: asciidoc,adoc,ad
+----
+asciidoc:
+  ext: asciidoc,adoc,ad
+----
 
 The extensions shown in the previous listing are the default values, so you don't need to specify this option if those defaults are sufficient.
 
-AsciiDoc attributes defined in the document header whose names begin with `page-` are promoted to Jekyll front matter.
+AsciiDoc attributes defined in the document header whose names begin with `page-` are promoted to page variables.
 The part of the name after the `page-` prefix is used as the key (e.g., page-layout becomes layout).
-If you want to change this attribute prefix, add the following line to your [path]_{empty}_config.yml_:
+If you want to change this attribute prefix, append the `page_attribute_prefix` option to the `asciidoc` block of your {path-config}:
 
 [source,yaml]
-asciidoc_page_attribute_prefix: jekyll
+----
+asciidoc:
+  page_attribute_prefix: jekyll
+----
 
 A hyphen is automatically added to the value of this configuration setting if the value is non-empty.
 
-To pass additional attributes to AsciiDoc, or override the default attributes defined in the plugin, add the following lines to your [path]_{empty}_config.yml_:
+Since version 2.0.0 of this plugin, all non-hidden AsciiDoc files are processed by default, even those without a front matter header.
+If you only want files containing a front matter header to be processed (as was the behavior prior to version 2.0.0), add the `require_front_matter_header` option to the `asciidoc` block of your {path-config}:
 
 [source,yaml]
+----
+asciidoc:
+  require_front_matter_header: true
+----
+
+=== Asciidoctor
+
+In addition to the built-in attributes in AsciiDoc, the following additional AsciiDoc attributes are automatically defined by this plugin and available to all AsciiDoc-based pages:
+
+....
+site-root=(absolute path of root directory)
+site-source=(absolute path of source directory)
+site-destination=(absolute path of output directory)
+site-baseurl=(value of the baseurl config option)
+site-url=(value of the url config option)
+env=site
+env-site
+site-gen=jekyll
+site-gen-jekyll
+builder=jekyll
+builder-jekyll
+jekyll-version=(value of the Jekyll::VERSION constant)
+idprefix
+idseparator=-
+linkattrs=@
+....
+
+The following attributes are defined per page:
+
+....
+outpath=(path of page relative to baseurl)
+....
+
+You can pass additional attributes to AsciiDoc, or override default attributes provided by the plugin, by using the `attributes` option of the `asciidoctor` block in your {path-config}.
+The value of this option can either be an Array containing key-value pairs:
+
+[source,yaml]
+----
 asciidoctor:
   attributes:
-    - hardbreaks!
+    - idprefix=_
     - source-highlighter=pygments
     - pygments-css=style
+----
+
+or key-value pairs defined as a Hash:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+    idprefix: _
+    source-highlighter: pygments
+    pygments-css: style
+----
+
+You may use attribute references in the attribute value to reference any implicit or already defined attribute.
+For example, to set the `iconsdir` attribute based on the `imagesdir` attribute, use the following:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+    imagesdir: /images
+    iconsdir: '{imagesdir}/icons'
+----
+
+CAUTION: If the value begins with an attribute reference, and you are defining the attributes using the Hash structure, you must enclose the value in quotes.
+
+In addition to `attributes`, you can define any another option key (e.g., `safe`) that is recognized by the {uri-asciidoctor-manual}#ruby-api-options[Asciidoctor API].
+
+==== Specifying the Base Directory
+
+In Asciidoctor, the base directory (i.e., `base_dir` option) is used as the root when resolving non-nested, relative includes, among other paths.
+
+By default, this plugin does not specify a base directory when invoking the Asciidoctor API.
+Asciidoctor will therefore use the current working directory (i.e., the project root) as the base directory.
+
+If your source directory is not the project root, and you want Asciidoctor to use the source directory as the base directory, set the value of the `base_dir` option to `:source`.
+
+[source,yaml]
+----
+asciidoctor:
+  base_dir: :source
+  ...
+----
+
+If, instead, you want the base directory to track the directory of the document being processed, and you're using Jekyll 3 or better, you can set the value of the `base_dir` option to `:docdir`.
+Since the base directory is also the jail, we also recommend setting the `safe` option to `unsafe` so that you can still resolve paths outside of this directory.
+
+[source,yaml]
+----
+asciidoctor:
+  base_dir: :docdir
+  safe: unsafe
+  ...
+----
+
+IMPORTANT: The `:docdir` setting is not available when using Jekyll 2.
 
-=== Disabling hard line breaks
+You can also set the `base_dir` option to any relative or absolute path.
+In that case, the same value will be used for all documents.
 
-The Jekyll AsciiDoc integration is configured to preserve hard line breaks in paragraph content by default.
-Since many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), this default was selected to ease the transition to AsciiDoc.
-If you want the standard AsciiDoc behavior of collapsing hard line breaks in paragraph content, add the following settings to your site's [path]_{empty}_config.yml_ file:
+==== Enabling Hard Line Breaks
+
+Many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), which preserves hard line breaks in paragraph content.
+Asciidoctor supports this feature for AsciiDoc files.
+(In fact, previous versions of this plugin enabled this behavior by default).
+If you want to enable this behavior for AsciiDoc files, add the `hardbreaks-option` attribute to the Asciidoctor attributes configuration in your site's {path-config} file:
 
 [source,yaml]
+----
 asciidoctor:
   attributes:
-    - hardbreaks!
+    - hardbreaks-option
+----
+
+If you want to allow individual files to override this setting, then assign the value `@` to the attribute:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+    - hardbreaks-option=@
+----
+
+If you already have AsciiDoc attributes defined in the {path-config}, the new attribute should be added as a sibling entry in the YAML collection.
+
+WARNING: Keep in mind, if you enable hard line breaks, you won't be able to use the {uri-asciidoc-practices}#one-sentence-per-line[one sentence-per-line writing technique].
+
+== Running in Safe Mode
+
+If you want to use this plugin when running Jekyll in safe mode, you must add the [app]*jekyll-asciidoc* gem to the whitelist in your site's {path-config} file:
 
-If you already have AsciiDoc attributes defined in the [path]_{empty}_config.yml_, the `hardbreaks!` attribute should be added as a sibling entry in the YAML collection.
+[source,yaml]
+----
+whitelist:
+  - jekyll-asciidoc
+----
+
+Safe mode is enabled either through the `--safe` flag:
+
+ $ jekyll build --safe 
+
+or the `safe` configuration option in your site's {path-config} file:
+
+[source,yaml]
+----
+safe: true
+----
+
+== Customizing the Generated HTML
+
+You can use templates to customize the HTML output that Asciidoctor generates for your site.
+Template files can be composed in any templating language that is supported by {uri-tilt}[Tilt].
+Each template file corresponds to a node in the AsciiDoc document tree (aka AST).
+
+Below are the steps you need to take to configure Asciidoctor to use custom templates with your site.
+
+=== Step 1: Add Required Gems
+
+You'll first need to add the thread_safe gem as well as the gem for the templating language you plan to use.
+We'll assume that you are using Slim.
+
+[source,ruby]
+----
+gem 'slim', '~> 3.0.7'
+gem 'thread_safe', '~> 0.3.5'
+----
+
+=== Step 2: Install New Gems
+
+Now run the `bundle` command to install the new gems.
+
+ $ bundle
 
-== Enabling Asciidoctor Diagram (optional)
+=== Step 3: Create a Templates Folder
 
-Asciidoctor Diagram is a set of extensions for Asciidoctor that allow you to embed diagrams written using the PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents.
+Next, create a new folder in your site named [path]__templates_ to store your templates.
+
+ $ mkdir _templates
+
+=== Step 4: Configure Asciidoctor to Load Templates
+
+In your site's {path-config} file, configure Asciidoctor to load the templates by telling it the location where the templates are stored.
+
+[source,yaml]
+----
+asciidoctor:
+  template_dir: _templates
+  attributes: ...
+----
+
+=== Step 5: Compose a Template
+
+The final step is to compose a template.
+We'll be customizing the unordered list node.
+Name the file [path]_ulist.html.slim_.
+
+.ulist.html.slim
+[source,slim]
+----
+- if title?
+  figure.list.unordered id=id
+    figcaption=title
+    ul class=[style, role]
+      - items.each do |_item|
+        li
+          span.primary=_item.text
+          - if _item.blocks?
+            =_item.content
+- else
+  ul id=id class=[style, role]
+    - items.each do |_item|
+      li
+        span.primary=_item.text
+        - if _item.blocks?
+          =_item.content
+----
+
+The next time you build your site, Asciidoctor will use your custom template to generate the HTML for unordered lists.
+
+TIP: You can find additional examples of custom templates in the {uri-asciidoctor-backends}[asciidoctor-backends] repository.
+
+== Enabling Asciidoctor Diagram
+
+{uri-asciidoctor-diagram}[Asciidoctor Diagram] is a set of extensions for Asciidoctor that allow you to embed diagrams generated by PlantUML, Graphviz, ditaa, Shaape, and other plain-text diagram tools inside your AsciiDoc documents.
+In order to use Asciidoctor Diagram in a Jekyll project successfully, *you must use Jekyll >= 3.0.0 and a version of this plugin >= 2.0.0*.
+Other combinations are known to have issues.
 
 [IMPORTANT]
-For Graphviz and PlantUML diagram generation, http://www.graphviz.org[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
+For Graphviz and PlantUML diagram generation, {uri-graphviz}[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
 
 === Installation
 
 Using Bundler::
 +
 --
-Add `asciidoctor-diagram` gem to your [path]_Gemfile_
+Add `asciidoctor-diagram` gem to your [path]_Gemfile_:
 
-[source,ruby]
+[source,ruby,subs=attributes+]
 ----
 group :jekyll_plugins do
-  ....
-  gem 'asciidoctor-diagram', '>= 1.3.1' <1>
+  gem 'asciidoctor-diagram', '~> 1.4.0' #{conum-guard}<1>
+  gem 'jekyll-asciidoc'
   ...
 end
 ----
-<1> version can be configured differently
+<1> Customize the version of Asciidoctor Diagram as needed.
 
 Then, run the Bundler command to install it:
 
@@ -224,74 +540,156 @@ Without Bundler::
 --
 Install gems manually
 
- $ gem install asciidoctor-diagram
+ $ [sudo] gem install asciidoctor-diagram
 
-Then, add the `asciidoctor-diagram` gem to the list of gems for Jekyll to load in your site's [path]_{empty}_config.yml_ file:
+Then, add the `asciidoctor-diagram` gem to the list of gems for Jekyll to load in your site's {path-config} file:
 
 [source,yaml]
+----
 gems:
   - asciidoctor-diagram
+  - jekyll-asciidoc
+----
 --
 
-Both of the previous configurations are the equivalent of passing `-r asciidoctor-diagram` to the `asciidoctor` command.
+The preceding configurations are equivalent to passing `-r asciidoctor-diagram` to the `asciidoctor` command.
+
+=== Generated Image Location
 
-=== Generated image location
+Asciidoctor Diagram needs some context in order to write the images to the proper location.
+At a minimum, you must set the following configuration in {path-config}:
 
-By default diagram images are generated in the root folder.
-Thus, images URLs are not properly referenced from the generated HTML pages.
+[source,yaml]
+----
+asciidoctor:
+  base_dir: :docdir
+  safe: unsafe
+----
 
-To fix this, set the `imagesdir` attribute in any AsciiDoc file that contains diagrams.
+With this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., into the same directory).
 
-._posts/2015-12-24-diagrams.adoc
-[listing]
-....
----
----
-= Diagrams
-:imagesdir: /images/2015-12-24 <1>
+You can use the following example to test your setup:
 
-[graphviz, dot-example, svg]
+._posts/2016-01-01-diagram-sample.adoc
+[source,asciidoc]
 ----
+= Diagram Sample
+
+[graphviz,dot-example,svg]
+....
 digraph g {
     a -> b
     b -> c
     c -> d
     d -> a
 }
-----
 ....
-<1> the date in the imagesdir value must match the date of the post (e.g., 2015-12-24)
+----
+
+If you prefer to serve all images from the same folder, assign a value to the `imagesdir` attribute that is relative to the site root:
+
+[source,yaml]
+----
+asciidoctor:
+  base_dir: :docdir
+  safe: unsafe
+  attributes:
+    imagesdir: /images
+----
+
+With this configuration, all images will be generated into the [path]_images_ directory inside the destination folder.
+
+==== Preserving Generated Images
+
+Since Asciidoctor Diagram writes to the output folder, you have instruct Jekyll not to remove these generated files.
+One way to do this is to apply a "`monkeypatch`" to Jekyll.
+Add the file [path]_jekyll-ext.rb_ to the [path]__plugins_ folder of your project root (creating the folder if it does not already exist) and populate the file with the following content:
+
+._plugins/jekyll-ext.rb
+[source,ruby]
+----
+class Jekyll::Cleaner
+  def cleanup!; end
+end
+----
 
-WARNING: The images are generated after Jekyll copies assets to the [path]_{empty}_site_ directory.
-Therefore, you'll have to run `jeykll` twice before you see the images in the preview.
+An alternative to the monkeypath approach is to identify folders that contain generated images in the `keep_files` option in {path-config}:
+
+[source,yaml]
+----
+keep_files: [images]
+asciidoctor:
+  base_dir: :docdir
+  safe: unsafe
+  attributes:
+    imagesdir: /images
+----
 
-== Supplemental AsciiDoc Assets
+== Adding Supplemental Assets
 
 Certain Asciidoctor features, such as icons, require additional CSS rules and other assets to work.
 These CSS rules and other assets do not get automatically included in the pages generated by Jekyll.
 This section documents how to configure these additional resources.
 
-TIP: If you want to take a shortcut that skips all this configuration, clone the https://github.com/asciidoctor/jekyll-asciidoc-quickstart[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
+TIP: If you want to take a shortcut that skips all this configuration, clone the {uri-jaq}[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
 JAQ provides a page layout out of the box configured to fully style body content generated from AsciiDoc.
 
 === Setup
 
 The Jekyll AsciiDoc plugin converts AsciiDoc to embeddable HTML.
 This HTML is then inserted into the page layout.
-You need to augment the page layout to include resources typically present in a standalone HTML document that Asciidoctor produces.
+You need to augment the layout to include resources typically present in a standalone HTML document that Asciidoctor produces.
 
 . Create a stylesheet in the [path]_css_ directory named [path]_asciidoc.css_ to hold additional CSS for body content generated from AsciiDoc.
 . Add this stylesheet to the HTML `<head>` in [path]_{empty}_includes/head.html_ under the main.css declaration:
 +
 [source,html]
+----
 <link rel="stylesheet" href="{{ "/css/asciidoc.css" | prepend: site.baseurl }}">
+----
+
+=== Stylesheet for Code Highlighting
+
+Asciidoctor integrates with Pygments to provide code highlighting of source blocks in AsciiDoc content.
+This integration is separate from the Pygments integration in Jekyll.
+As part of this integration, Asciidoctor generates a custom stylesheet tailored specially to work with the HTML that Asciidocotor produces.
+Since this stylesheet is backed by the Pygments API, it provides access to all the themes in Pygments
+
+This plugin will automatically generate a stylesheet for Pygments into the source directory if the AsciiDoc attributes in your site's {path-config} are configured as follows:
+
+* `source-highlighter` has the value `pygments`
+* `pygments-css` has the value `class` or is not set
+* `pygments-stylesheet` is not unset (if set, it can have any value)
+
+By default, the stylesheet is written to `stylesdir` + `pygments-stylesheet`.
+If the `pygments-stylesheet` attribute is not specified, the value defaults to `asciidoc-pygments.css`.
+You can customize this value to your liking.
+
+The Pygments theme is selected by the value of the `pygments-style` attribute.
+If this attribute is not set, it defaults to `vs`.
+
+The stylesheet file will be created if it does not yet exist or the theme has been changed.
+Jekyll will handle copying the file to the output directory.
+
+You'll need to add a line to your template to link to this stylesheet, such as:
+
+[source,html]
+----
+<link rel="stylesheet" href="{{ "/css/asciidoc-pygments.css" | prepend: site.baseurl }}">
+----
+
+To disable this feature, either set the `pygments-css` to `style` (to enable inline styles) or unset the `pygments-stylesheet` attribute in your site's {path-config}.
+
+NOTE: It may still be necessary to make some tweaks to your site's stylesheet to accomodate this integration.
 
 === Font-based Admonition and Inline Icons
 
 To enable font-based admonition and inline icons, you first need to add Font Awesome to [path]_{empty}_includes/head.html_ file under the asciidoc.css declaration:
 
 [source,html]
+----
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css">
+----
 
 NOTE: You can also link to local copy of Font Awesome.
 
@@ -338,15 +736,20 @@ Feel free to modify the CSS to your liking.
 
 Finally, you need to enable the font-based icons in the header of the document:
 
- :icons: font
+[source,asciidoc]
+----
+:icons: font
+----
 
 or in the site configuration:
 
 [source,yaml]
+----
 asciidoctor:
   attributes:
     - icons=font
     ...
+----
 
 === Image-based Admonition and Inline Icons
 
@@ -355,33 +758,310 @@ In this case, all you need to do is provide the icons at the proper location.
 
 First, enable image-based icons and configure the path to the icons in the header of the document:
 
- :icons:
- :iconsdir: /images/icons
+[source,asciidoc]
+----
+:icons:
+:iconsdir: /images/icons
+----
 
 or your site configuration:
 
 [source,yaml]
+----
 asciidoctor:
   attributes:
     - icons
     - iconsdir=/images/icons
+----
 
 Then, simply put the icon images that the page needs in the [path]_images/icons_ directory.
 
-== GitHub Pages
+== Converting AsciiDoc in Templates
+
+Jekyll uses the Liquid templating language to process templates.
+This plugin defines an additional filter named `asciidocify` for converting a string of AsciiDoc.
+
+Let's assume the excerpt of the post is written in AsciiDoc.
+You can convert it in your template as follows:
+
+----
+{{ post.excerpt | asciidocify }}
+----
+
+If you only want to perform inline substitutions on the content, add the `inline` doctype as the first argument:
+
+----
+{{ post.excerpt | asciidocify: 'inline' }}
+----
+
+This filter allows you to compose site-wide data in AsciiDoc, such your site's description or synopsis, then convert it to HTML for use in the page template(s).
+
+== Using this Plugin on GitHub Pages
 
-GitHub doesn't (yet) whitelist the AsciiDoc plugin, so you can only run it on your own machine.
+GitHub doesn't (yet) whitelist the AsciiDoc plugin, so you must run Jekyll either on your own computer or on a continuous integration (CI) server.
 
-TIP: GitHub needs to hear from enough users that they want to plugin in order to enable it.
-Our recommendation is to keep lobbying for them to enable it.
+[IMPORTANT]
+====
+GitHub needs to hear from enough users that need this plugin to persuade them to enable it.
+Our recommendation is to https://github.com/contact[contact support] and keep asking for it.
+
+Refer to the help page https://help.github.com/articles/adding-jekyll-plugins-to-a-github-pages-site/[Adding Jekyll Plugins to a GitHub Pages site] for a list of plugins currently supported on GitHub Pages.
+====
 
 You can automate publishing of the generated site to GitHub Pages using a continuous integration job.
 Refer to the tutorial http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html[Automate GitHub Pages publishing with Jekyll and Travis CI^] to find step-by-step instructions to setup this job.
 You can also refer to the https://github.com/johncarl81/transfuse-site[Tranfuse website build^] for an example in practice.
 
-Refer to the https://help.github.com/articles/using-jekyll-plugins-with-github-pages[Jekyll Plugins on GitHub Pages] for a list of the plugins currently supported on the server-side (in addition to Markdown, which isn't listed).
+TIP: If you want to take a shortcut that skips all the steps in the tutorial, clone the {uri-jaq}[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
+JAQ provides a page layout out of the box configured to fully style body content generated from AsciiDoc.
+
+== Using this Plugin on GitLab Pages
+
+Deployment to GitLab Pages is much simpler.
+That's because GitLab allows you to control the execution of Jekyll yourself.
+There's no need to mess around with CI jobs and authentication tokens.
+You can find all about how to use Jekyll with GitLab Pages in the tutorial https://about.gitlab.com/2016/04/07/gitlab-pages-setup/#option-b-gitlab-ci-for-jekyll-websites[Hosting on GitLab.com with GitLab Pages].
+
+Assuming the following are true:
+
+. The source of your site resides on the master branch.
+. You're using Bundler to manage the dependencies for your project.
+
+then you can use the following [path]_.gitlab-ci.yml_ file to get starting hosting your Jekyll site on GitLab Pages.
+
+.gitlab-ci.yml
+[source,yaml]
+----
+image: ruby:2.3
+cache:
+  paths: 
+    - .bundle
+before_script:
+  - bundle --path .bundle/gems
+pages:
+  script:
+    - bundle exec jekyll build -d public --config _config.yml,_config-gitlab.yml -q
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
+----
+
+This script runs Jekyll on the official Ruby Docker container.
+
+You also need to add and additional configuration file, [path]__config-gitlab.yml_, to set the `url` and `baseurl` options when deploying your site to GitLab Pages.
+
+._config-gitlab.yml
+[source,yaml,subs=attributes+]
+----
+url: https://<username>.gitlab.io #{conum-guard}<1>
+baseurl: /<projectname> #{conum-guard}<2>
+----
+<1> Replace `<username>` with your GitLab username or group.
+<2> Replace `<projectname>` with the basename of your project repository.
+
+The next time you push to the master branch, the GitLab Pages runner will execute Jekyll and deploy your site to [uri]_\https://<username>.gitlab.io/<projectname>_, where `<username>` is your GitLab username or group and `<projectname>` is the basename of your project repository.
+
+Like GitHub Pages, you can also have your site respond to a custom domain name, which is explained in the referenced tutorial.
+In this case, update the [path]__config-gitlab.yml_ file with the appropriate values.
+
+== Getting Help
+
+The Jekyll AsciiDoc plugin is developed to help you publish your content quickly and easily.
+But we can't achieve that goal without your input.
+Your questions and feedback help steer the project, so speak up!
+Activity drives progress.
+
+When seeking answers, always start with the official documentation for Jekyll, which can be found on the {uri-jekyll}[Jekyll website].
+If you have general questions about Jekyll, we recommend you visit the {uri-jekyll-discuss}[Jekyll Talk] forum to get assistance.
+For questions related to this extension specifically, or general questions about AsciiDoc, please post to the {uri-asciidoctor-discuss}[Asciidoctor discussion list].
+You can also join us in the {uri-chat}[asciidoctor/asciidoctor channel] on Gitter.
+For general information about AsciiDoc, look no further than the {uri-asciidoctor-manual}[Asciidoctor User Manual].
+
+=== Filing Bug Reports and Feature Requests
 
-== Releasing the gem to RubyGems.org
+This project uses the {uri-issues}[GitHub issue tracker] to manage bug reports and feature requests.
+If you encounter a problem, please {uri-search-issues}[browse or search] the issues to find out if your problem has already been reported.
+If it has not, you may {uri-issues}/new[submit a new issue].
+
+The best way to get a timely response and quick fix for your issue is to write a detailed report and respond to replies in a timely manner.
+
+If you know Ruby (or you're willing to learn), we encourage you to submit a pull request.
+Please include an RSpec behavior that describes how your feature should work or demonstrates the problem you're encountering.
+Make sure to send your pull request from a branch in your fork.
+If the pull request resolves an issue, please name the branch using the issue number (e.g., issue-N, where N is the issue number).
+
+If you aren't able to submit a pull request, please provide a sample so that the developers can reproduce your scenario.
+
+== Development
+
+To help develop the Jekyll AsciiDoc plugin, or to simply use the development version, you need to retrieve the source from GitHub.
+Follow the instructions below to learn how to clone the source, run the tests and install the development version.
+
+=== Retrieve the Source Code
+
+You can retrieve the source code from GitHub using git.
+Simply copy the URL of the {uri-repo}[GitHub repository] and pass it to the `git clone` command:
+
+[subs=attributes+]
+....
+git clone {uri-repo}
+....
+
+Next, switch to the project directory.
+
+ $ cd jekyll-asciidoc
+
+=== Install the Dependencies
+
+The dependencies needed to develop the Jekyll AsciiDoc plugin are defined in the [path]_Gemfile_ at the root of the project.
+You'll use Bundler to install these dependencies.
+
+To check if you have Bundler installed, use the `bundle` command to query for the version:
+
+ $ bundle --version
+
+If Bundler is not installed, use the `gem` command to install it.
+
+ $ [sudo] gem install bundler
+
+Finally, invoke the `bundle` command (which is provided by the bundler gem) from the root of the project to install the dependencies into the project:
+
+ $ bundle --path=.bundle/gems
+
+IMPORTANT: Since we've installed dependencies inside the project, it's necessary to prefix all commands (e.g., rake) with `bundle exec`.
+
+=== Running the Tests
+
+The tests are based on RSpec.
+The test suite is located in the [path]_spec_ directory.
+
+You can run the tests using Rake.
+
+ $ bundle exec rake spec
+
+For more fine-grained control, you can also run the tests using RSpec directly.
+
+ $ bundle exec rspec
+
+If you only want to run a selection of tests, you can do so by assigning those specifications a tag and filtering the test run accordingly.
+
+Start by adding the `focus` tag to one or more specifications:
+
+[source,ruby]
+----
+it 'should register AsciiDoc converter', focus: true do
+  expect(site.converters.any? {|c| ::Jekyll::AsciiDoc::Converter === c }).to be true
+end
+----
+
+Then, run RSpec with the `focus` flag enabled:
+
+ $ bundle exec rspec -t focus
+
+You should see that RSpec only runs the specifications that have this flag.
+
+=== Installing the Gem Locally
+
+You can install the development version of the gem as follows:
+
+ $ bundle exec rake install
+
+This allows you to use an unreleased version of the gem in your site.
+If you want to build the gem and install it manually, use these commands instead:
+
+ $ bundle exec rake build
+ $ [sudo] gem install pkg/jekyll-asciidoc-*.dev.gem
+
+=== Coding Style
+
+This project adheres to the coding style used throughout the Asciidoctor project.
+The coding style is as follows:
+
+* Indent using 2 spaces, generally.
+
+* Indent successive lines of conditions, method arguments or ternary expressions using 4 spaces (but not data structures or chained method calls).
+
+* Don't indent `when` lines in a case block.
+
+* Fully qualify the class name (beginning with `::`) of any type not in the current namespace.
+
+  ::File.extname path 
+
+* Use triple equals to check for type, placing the type on the left hand side.
+
+  ::Hash === attrs
+
+* Drop parentheses around method arguments of a method definition.
+
+  def integrate document, collection_name = nil
+    ...
+  end
+
+* Drop parentheses around method arguments of an isolated method call.
+
+  source = ::File.expand_path config['source']
++
+  if key.start_with? '!'
+    ...
+  end
++
+  asciidoctor_config.replace Utils.symbolize_keys asciidoctor_config
+
+* Use parentheses outside of a method call when parentheses are required.
+
+  layout = collection_name ? (collection_name.chomp 's') : 'page'
++
+  if (::Jekyll::Utils.method dlg_method.name).arity == -1
+    ...
+  end
+
+* Use parentheses where required, such as around the accumulator seed value for a collection predicate.
+
+  hash.each_with_object({}) {|(key, val), accum| accum[key.to_sym] = val }
+
+* Don't put curly braces around entries in an options Hash (i.e., symbol keys).
+
+  record_path_info document, source_only: true
+
+* Use a trailing condition for single-line statements.
+
+  clear_path_info if Document === document
+
+* Put parantheses around a variable assignment inside a condition.
+
+  if (imagesdir = attrs['imagesdir'])
+
+* Use simple check for nil.
+
+  if base 
+
+* Use `%()` instead of double quotes around interpolated strings.
+
+  %(--- #{val})
+
+* Name constants using pascal style.
+
+  NewLine = %(\n)
+
+* Store each static regular expression in a constant.
+
+  HeaderBoundaryRx = /(?<=\p{Graph})\n\n/
+
+* Use parentheses in traditional style when writing test assertions.
+
+  expect(site.config['asciidoc']['processor']).to eql('asciidoctor')
+  expect(result.key? 'icons').to be true
+  expect(contents).to match('<div class="page-content">')
+
+////
+* use `do; end` for multi-line blocks; use `{}` for single-line blocks
+* try to make assignments in condition if scoped to that block
+* close empty block on same line if empty - `rescue ::NameError; end`
+////
+
+=== Releasing the Gem
 
 When you are ready for a release, first set the version in the file [path]_lib/jekyll-asciidoc/version.rb_.
 Then, commit the change using the following commit message template:
@@ -392,8 +1072,38 @@ where `X.Y.Z` is the version number of the gem.
 
 Next, package, tag and release the gem to RubyGems.org, run the following rake task:
 
- $ rake release
+ $ bundle exec rake release
+
+IMPORTANT: Ensure you have the proper credentials setup as described in the guide {uri-guide-publish-gem}[Publishing to RubyGems.org].
+
+Once you finish the release, you should update the version to the next micro version in the sequence using the `.dev` suffix (e.g., 2.0.1.dev).
+
+== About the Project
+
+The Jekyll AsciiDoc plugin, a plugin for the static site generator {uri-jekyll}[Jekyll], is a member project of the Asciidoctor organization.
+This plugin is developed and supported by volunteers in the Asciidoctor community.
+
+=== Authors
+
+This plugin was created by Dan Allen and Paul Rayner and has received contributions from many other individuals in the Asciidoctor community.
+
+=== Copyright and License
+
+Copyright (C) 2013-2016 Dan Allen, Paul Rayner, and the Asciidoctor Project.
+Free use of this software is granted under the terms of the MIT License.
+See <<LICENSE#,LICENSE>> for details.
+
+////
+[glossary]
+== Glossary
 
-IMPORTANT: Ensure you have the proper credentials setup as described in the guide http://guides.rubygems.org/publishing/#publishing-to-rubygemsorg[Publishing to RubyGems.org].
+[glossary]
+page variable::
+Data associated with a page, post or document.
+Page variables are defined in the front matter header or as page attributes in the AsciiDoc header.
 
-Once you finish the release, you should update the version to the next micro version in the sequence using the `.dev` suffix (e.g., 1.0.1.dev).
+page attribute::
+Any AsciiDoc attribute that gets promoted to a page variable by this plugin.
+Before being promoted, the designated prefix is removed from the name.
+The value of a page attribute is parse as YAML data.
+////