jekyll-asciidoc 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f0880454bf13707df6ab46db960a614e543e1d5
-  data.tar.gz: 91f7795b3722073aca1a3ab2c49a0d04f9883033
+  metadata.gz: c4135124b7d7842c3e199e5208d4c267e87a259d
+  data.tar.gz: 0d4051c81249eb6259e97bab4a0dc3c91c1e881b
 SHA512:
-  metadata.gz: 4e865f7e9ef44ee8b8626b6948fa184d50bfd3bb8d799065e2f89dddbfc3a2a97ab5e54f6b98afe66aee5c3d771fab0a51703cbb92c6f8a10b715ada0c59256e
-  data.tar.gz: 8e210f65e121dd1d208e9b7492bf3f3f1af6284e0d433ee1e8c3fe844f3de64d7e27df163b899df347189d5fdb87c6d7dc4ac867c8cc11c483e10b212537844f
+  metadata.gz: f18fd97d2472bec92a0ddecaaca4fd6d31a10f5620ade52f81e6f20fc00e1adf4c4d4410c06864cbb1bdffab4dcb2a64f6762db4363c0d5b678f8f3c5a7e680c
+  data.tar.gz: f377c0cfc83c0ca2edd23009011412aacbd7f302d6d636e064d9699a867ec4681b82eed07fadc1ba6982a6b7608f2a9eb6178153c781063fdf4da19c9a7c722e

data/CHANGELOG.adoc

@@ -5,29 +5,48 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 2.1.0 (2017-05-21) - @mojavelinux
+
+* Add `tocify_asciidoc` Liquid filter for generating a table of contents from the parsed AsciiDoc document (Jekyll 3+ only) (#37)
+* Remove trailing `@` when resolving attribute reference in value of attribute defined in config
+* Set minimum version of Ruby to 1.9.3 in the gemspec
+* Prefixing attribute defined in config with minus removes previously defined (e.g., built-in) attribute (#123)
+* Convert attribute values in config as follows: true becomes empty string; false becomes nil, number becomes string (#127)
+* Merge category page variable into categories variable and tag page variable into tags variable (#149)
+* Assign document ID to page variable named docid (#146)
+* Enable CI for Windows platform by configuring job on AppVeyor
+* Catch SyntaxError when using Psych YAML parser with Ruby 1.9.3
+* Document that the name of page variable created from a page attribute is automatically lowercased
+* Parse the value of the revdate attribute using `Jekyll::Utils.parse_date`
+* Document how to assign a specific time to a post
+* Document how to make site-wide AsciiDoc attributes accessible to Liquid templates (#137)
+* Fix crash when converting an auto-extracted excerpt when base_dir option is set to :docdir
+* Add additional documentation and make other minor improvements to the README
+
 == 2.0.1 (2016-07-06) - @mojavelinux
 
-* align localtime and localdate attributes with site.time and site.timezone (#117)
-* don't register hook callbacks again when regenerating site; use static methods for hook callbacks (#121)
-* bundle CHANGELOG.adoc and test suite in gem
-* minor improvements to README
+* Align localtime and localdate attributes with site.time and site.timezone (#117)
+* Don't register hook callbacks again when regenerating site; use static methods for hook callbacks (#121)
+* Bundle CHANGELOG.adoc and test suite in gem
+* Minor improvements to README
 
 == 2.0.0 (2016-07-02) - @mojavelinux
 
 * Split source into multiple files; move all classes under the `Jekyll::AsciiDoc` module
 * Avoid redundant initialization caused by the jekyll-watch plugin
-* Set docdir, docfile, docname, outfile, outdir, and outpath attributes for each file if using Jekyll 3 (#59)
+* Set docdir, docfile, docname, outfile, outdir, and outpath attributes for each file (Jekyll 3+ only) (#59)
   - docdir is only set if value of `base_dir` option is `:docdir`
   - setting outdir allows proper integration with Asciidoctor Diagram
 * Automatically set `imagesoutdir` attribute if `imagesdir` attribute is relative to root
 * Pass site information (root, source, destination, baseurl and url) through as AsciiDoc attributes
 * Automatically generate stylesheet for Pygments (#30)
 * Change default layout to match collection label (#104)
-  - page for pages, post for posts, collection label for all others; use default layout as fallback
+  - page for pages, post for posts, collection label for all others
+  - use layout named default as fallback
 * Resolve attribute references in attribute values defined in config (#103)
 * Apply AsciiDoc header integration to documents in all collections (#93)
 * Document how to create and enable templates to customize the HTML that Asciidoctor generates (#73)
-* Allow `base_dir` option to track document directory by setting the value to `:docdir` (#80)
+* Allow `base_dir` option to track document directory by setting the value to `:docdir` (Jekyll 3 only) (#80)
 * Add a comprehensive test suite (#77)
 * Allow site-wide Asciidoctor attributes to be specified as a Hash; convert to Hash if Array is used (#87)
 * Interpret page attribute values as YAML data
@@ -45,7 +64,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * Allow plugin to work in safe mode (#112)
 * Major restructure and rewrite of README
 * Document how to use plugin with GitLab Pages (#47)
-* Document asciidocify filter
+* Document `asciidocify` Liquid filter
 
 {uri-repo}/issues?q=milestone%3Av2.0.0[issues resolved] |
 {uri-repo}/releases/tag/v2.0.0[git tag]

data/Gemfile

@@ -2,9 +2,19 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'jekyll', %(~> #{ENV['JEKYLL_VERSION']}) if ENV.key? 'JEKYLL_VERSION'
+# NOTE Windows does not include zoneinfo files, so load tzinfo-data gem
+gem 'tzinfo-data', platform: :mingw
 
-if RUBY_ENGINE == 'jruby'
-  gem 'pygments.rb', github: 'mojavelinux/pygments.rb', branch: 'support-jruby'
-else
+if (ENV.key? 'JEKYLL_VERSION') && (Gem::Version.new ENV['JEKYLL_VERSION']) < (Gem::Version.new '3.0.0')
+  if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0.0')
+    # NOTE downgrade ffi to support Ruby 1.9.3
+    gem 'ffi', '1.9.14', platform: :mingw
+    # NOTE downgrade octokit to support Ruby 1.9.3
+    gem 'octokit', '~> 4.2.0'
+  end
+  # NOTE pygments.rb 0.6.3 is not compatible with Ruby >= 2.4
   gem 'pygments.rb', '~> 0.6.3'
+else
+  # NOTE pygments.rb >= 1.1.0 includes support for JRuby
+  gem 'pygments.rb', '~> 1.1.2'
 end

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2013-2016 Dan Allen and the Asciidoctor Project
+Copyright (C) 2013-2017 Dan Allen, Paul Rayner, 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

data/README.adoc

@@ -1,12 +1,12 @@
 = Jekyll AsciiDoc Plugin (powered by Asciidoctor)
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Paul Rayner <https://github.com/paulrayner[@paulrayner]>
-v2.0.1, 2016-07-06
+v2.1.0, 2017-05-21
 // Settings:
 :idprefix:
 :idseparator: -
 ifndef::env-github[:icons: font]
 ifdef::env-github,env-browser[]
-:toc: preamble
+:toc: macro
 :toclevels: 1
 endif::[]
 ifdef::env-github[]
@@ -20,7 +20,7 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 // Aliases:
-:path-config: pass:q[[path]___config.yml__]
+:path-config: pass:q[[.path]___config.yml__]
 :conum-guard: {sp}
 ifndef::icons[:conum-guard: {sp}#{sp}]
 // URIs:
@@ -28,7 +28,8 @@ ifndef::icons[:conum-guard: {sp}#{sp}]
 :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-ci-travis: https://travis-ci.org/asciidoctor/jekyll-asciidoc
+:uri-ci-appveyor: https://ci.appveyor.com/project/asciidoctor/jekyll-asciidoc
 :uri-gem: http://rubygems.org/gems/jekyll-asciidoc
 :uri-gem-asciidoctor: http://rubygems.org/gems/asciidoctor
 :uri-asciidoc: http://asciidoc.org
@@ -45,17 +46,32 @@ ifndef::icons[:conum-guard: {sp}#{sp}]
 :uri-jekyll-discuss: https://talk.jekyllrb.com
 :uri-front-matter: {uri-jekyll-docs}/frontmatter
 :uri-liquid-templates: {uri-jekyll-docs}/templates
+:uri-variables: {uri-jekyll-docs}/variables
 :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={uri-gem}]
-image:https://img.shields.io/travis/asciidoctor/jekyll-asciidoc/master.svg[Build Status (Travis CI), link={uri-ci}]
+image:https://img.shields.io/gem/v/jekyll-asciidoc.svg[Latest Release, link={uri-gem}]
+image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright-and-license]
+image:https://img.shields.io/travis/asciidoctor/jekyll-asciidoc/master.svg[Build Status (Travis CI), link={uri-ci-travis}]
+image:https://ci.appveyor.com/api/projects/status/3cf1f8p2cyoaoc25/branch/master?svg=true&passingText=green%20bar&failingText=%23fail&pendingText=checking[Build Status (AppVeyor), link={uri-ci-appveyor}]
 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].
+A plugin for {uri-jekyll}[Jekyll] (>= 2.3.0) that converts the {uri-asciidoc}[AsciiDoc] source files in your site to HTML pages using {uri-asciidoctor}[Asciidoctor].
+
+ifeval::['{branch}' == 'master']
+NOTE: You're viewing the documentation for the upcoming release.
+If you're looking for the documentation for an older release, please refer to one of the following branches: +
+{uri-repo}/tree/2.0.x#readme[2.0.x]
+&hybull;
+{uri-repo}/tree/1.1.x#readme[1.1.x]
+&hybull;
+{uri-repo}/tree/1.0.x#readme[1.0.x]
+endif::[]
+
+toc::[]
 
 == Overview
 
@@ -66,23 +82,28 @@ Converts AsciiDoc files to HTML pages.
 This plugin currently uses Asciidoctor to convert AsciiDoc content.
 
 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).
+Promotes eligible AsciiDoc attributes (e.g., doctitle, id, author, and attributes that begin with the page attribute prefix) to page variables.
+These attributes are merged with the page variables defined in the front matter header.
 
-Liquid Filter -- `asciidocify`::
-A Liquid filter that uses the converter from this plugin to convert AsciiDoc content to HTML.
+Liquid Filters::
+* `asciidocify` -- Uses the converter from this plugin to convert a string of AsciiDoc content to HTML.
+* `tocify_asciidoc` -- Generates a table of contents in HTML from the parsed AsciiDoc document of the current page (since 2.1.0; only for Jekyll 3 or better and Asciidoctor).
 
-These extensions are registered automatically when the [app]*jekyll-asciidoc* gem is required.
+These extensions are registered automatically when the [.app]*jekyll-asciidoc* gem is required.
 
 == Installation
 
-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.
+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.
 
 Your method of installation will depend on whether you use Bundler to manage the dependencies for your Jekyll project.
 
+IMPORTANT: Jekyll relies on several native gems, so it's necessary to have the Ruby development headers (e.g., ruby.h) on your machine in order to install AsciiDoc Jekyll (due to the requirements of Jekyll).
+The instructions for how to install the Ruby development headers are platform-specific and outside of the scope of this document.
+
 === Installation Using Bundler
 
-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_:
+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]
 ----
@@ -104,7 +125,7 @@ If you're not using Bundler to manage the dependencies for your Jekyll project,
 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:
+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]
 ----
@@ -120,8 +141,7 @@ There are a few conditions that must be met in order for an AsciiDoc file to be
 . 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.
+. _(Optional beginning with version 2.0.0 of this plugin)_ Aside from posts, documents must begin with a {uri-front-matter}[front matter header].
 
 Here's a sample AsciiDoc file that meets these criteria:
 
@@ -159,12 +179,22 @@ Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
 puts "Hello, World!"
 ----
 
-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).
+=== Page Attributes
+
+Any AsciiDoc attribute defined in the AsciiDoc document header whose name begins with ``page-``footnote:[The prefix used to label page attributes can be customized.] gets promoted to a {uri-variables}[page variables].
+The part of the name after the `page-` prefix is _lowercased_ and used as the variable name (e.g., page-layout becomes layout).
+The value is processed as {uri-yaml}[YAML] data (single-line form).
+
+IMPORTANT: The AsciiDoc document header stops after the first blank line.
+You may use include directives in the the document header, but make sure the included file does not contain a blank line.
+
+TIP: Use either a hyphen or an underscore as a separator for page attributes with multiple words (e.g., page-short-name).
+
+=== Specifying a 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_.
+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.
@@ -173,16 +203,53 @@ 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_)
+* `: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:
+=== Implicit Page Variables
+
+In addition to page attributes defined explicitly (e.g., layout, permalink, etc), the following implicit AsciiDoc attributes are also promoted to page variables:
 
-* doctitle (i.e., the document title) (becomes title)
+* doctitle (aka the document title) (becomes title)
+* id (becomes docid)
 * author
-* revdate (becomes date; value is converted to a DateTime object; only for posts)
+* revdate (becomes date; value is converted to a DateTime object; posts only)
+
+==== Giving Your Post the Time of Day
+
+By default, all posts are assigned a date that is computed from the file name (e.g., the date for 2016-03-20-welcome.adoc is 2016-03-20).
+If you want to give your post a specific time as well, you can set the `revdate` attribute in the AsciiDoc header.
+
+We recommend using the format `YYYY-MM-DD HH:MM:SS Z` as shown in this example:
+
+[source,asciidoc]
+----
+= Post Title
+Author Name
+:revdate: 2016-03-20 10:30:00 -0600
+
+Lorem ipsum.
+----
+
+If you don't provide a time zone in the date, the date is assumed to be in the same time zone as the site (which is your local time zone by default).
+
+Alternatively, you can specify the date in the implicit revision line.
+In this case, you must substitute the colons in the time part with "h", "m", and "s", respectively, since the colon demarcates the revision remark.
+
+[source,asciidoc]
+----
+= Post Title
+Author Name
+2016-03-20 10h30m00s -0600
+
+Lorem ipsum.
+----
+
+Note that the revision line must be preceded by the implicit author line.
+
+=== Enabling Liquid Preprocessing
 
 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).
@@ -202,30 +269,47 @@ In these cases, you define all the page variables (e.g., layout) using AsciiDoc
 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:
+== Building and Previewing Your Site
+
+You can build your site into the [.path]__site_ directory using:
 
  $ jekyll build
 
-or preview it using:
+If you're using Bundler, prefix each command with `bundle exec`:
+
+[subs=+quotes]
+ $ *bundle exec* jekyll build
+
+You can preview your site at \http://localhost:4000 using:
 
  $ jekyll serve
 
-You can continuously build without preview using:
+Since Jekyll 2.4.0, the `serve` command monitors the file system and rebuilds the site whenever a change is detected by default (i.e., watch mode).
+You can enable watch mode explicitly using the `--watch` flag:
+
+ $ jekyll serve --watch
+
+To disable watch mode explicitly, use the `--no-watch` flag instead.
+
+You can also use the `--watch` flag with the `build` command:
 
  $ jekyll build --watch
 
-If you're using Bundler, prefix the commands with `bundle exec`, as in:
+If you only want Jekyll to build files which have changed, and not the whole site, add the `--incremental` flag:
 
- $ bundle exec jekyll build
+ $ jekyll serve --incremental
+
+or
+
+ $ jekyll build --watch --incremental
 
 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.
+IMPORTANT: If you add the `--safe` flag, third-party plugins such as this one are disabled by default.
+To reenable the plugin, you must add the name of the gem to the whitelist.
+See <<Running in Safe Mode>> for details.
 
 == Configuration
 
@@ -239,7 +323,7 @@ asciidoc: {}
 asciidoctor: {}
 ----
 
-Using these placeholder values is an optimization that prevents initialization from being performed more than once.
+Using these placeholder values prevents initialization from being performed more than once when using watch mode (see https://github.com/jekyll/jekyll/issues/4858[issue jekyll#4858]).
 
 === AsciiDoc
 
@@ -247,7 +331,7 @@ NOTE: Prior to version 2.0.0 of this plugin, the configuration keys in this sect
 These names are now deprecated, but still supported.
 
 By default, this plugin uses Asciidoctor to convert AsciiDoc files.
-Since Asciidoctor is currently the only option, the default setting is equivalent to the following configuration in {path-config}:
+Because Asciidoctor is currently the only option, the default setting is equivalent to the following configuration in {path-config}:
 
 [source,yaml]
 ----
@@ -278,7 +362,7 @@ asciidoc:
   page_attribute_prefix: jekyll
 ----
 
-A hyphen is automatically added to the value of this configuration setting if the value is non-empty.
+A hyphen is automatically added to the value of this configuration setting if the value is non-empty (e.g, jekyll-).
 
 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}:
@@ -340,6 +424,15 @@ asciidoctor:
     pygments-css: style
 ----
 
+When using the Hash syntax, you must use an empty string value to set a valueless attribute such as `sectanchors`:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+    sectanchors: ''
+----
+
 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:
 
@@ -351,13 +444,24 @@ asciidoctor:
     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.
+CAUTION: If the value begins with an attribute reference, and you're defining the attributes using the Hash structure, you must enclose the value in quotes.
+Beware that there are additional edge cases when the value must be enclosed 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].
+Since version 2.1.0 of this plugin, you can remove a previously defined attribute by prefixing the name with a minus sign (without any space between):
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+    -idprefix:
+----
+
+In addition to `attributes`, you may define any other option key (e.g., `safe`) recognized by the {uri-asciidoctor-manual}#ruby-api-options[Asciidoctor API].
+One of those is `base_dir`, which is covered in the next section.
 
 ==== 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.
+In Asciidoctor, the base directory (i.e., `base_dir` option) is used as the root when resolving relative include paths in top-level documents.
 
 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.
@@ -372,6 +476,7 @@ asciidoctor:
 ----
 
 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`.
+This behavior matches how Asciidoctor works when running it outside of Jekyll.
 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]
@@ -387,7 +492,40 @@ IMPORTANT: The `:docdir` setting is not available when using Jekyll 2.
 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.
 
-==== Enabling Hard Line Breaks
+==== Using AsciiDoc attributes in a Liquid template
+
+Let's say you want to reuse your AsciiDoc attributes in a Liquid template.
+This section describes how to do it.
+
+Liquid can only access simple data structures, not complex ones like the one used to store site-wide AsciiDoc attributes. (Site-wide AsciiDoc attributes are stored deep within the Jekyll configuration data as a Hash with symbol keys).
+This puts them out of the reach of Liquid templates by default.
+
+This plugin must store site-wide AsciiDoc attributes in this way due to how Jekyll is implemented and the lifecycle it exposes for plugins.
+That part can't be changed.
+The plugin is limited by Jekyll's design.
+However, YAML provides a mechanism that we can leverage to expose these attributes to our Liquid templates.
+
+First, you define your AsciiDoc attributes at the top level of your configuration file where Liquid is able to access them.
+If you also assign a YAML reference to this key, you can then pass that Hash to the attributes key in the asciidoctor block, thus allowing the configuration to be shared.
+
+[source,yaml]
+----
+asciidoc_attributes: &asciidoc_attributes
+  imagesdir=/images
+asciidoctor:
+  attributes: *asciidoc_attributes
+  ...
+----
+
+You can now reference one of the site-wide AsciiDoc attributes in the Liquid template as follows:
+
+----
+{{ site.asciidoc_attributes.imagesdir }}
+----
+
+Keep in mind that the value of the attribute will be unmodified from the value defined in the configuration file.
+
+==== Enabling Hard Line Breaks Globally
 
 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.
@@ -416,7 +554,7 @@ WARNING: Keep in mind, if you enable hard line breaks, you won't be able to use
 
 == 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 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:
 
 [source,yaml]
 ----
@@ -426,7 +564,7 @@ whitelist:
 
 Safe mode is enabled either through the `--safe` flag:
 
- $ jekyll build --safe 
+ $ jekyll build --safe
 
 or the `safe` configuration option in your site's {path-config} file:
 
@@ -435,6 +573,66 @@ or the `safe` configuration option in your site's {path-config} file:
 safe: true
 ----
 
+== Working with AsciiDoc Content in Templates
+
+Jekyll uses the Liquid templating language to process templates.
+This plugin defines two additional Liquid filters, `asciidocify` and `tocify_asciidoc`, for working with AsciiDoc content in those templates.
+
+=== Converting a String from AsciiDoc
+
+You can use the `asciidocify` filter to convert an arbitrary AsciiDoc string anywhere in your template.
+
+Let's assume the excerpt of the post is written in AsciiDoc.
+You can convert it in your template as follows:
+
+----
+{{ post.excerpt | asciidocify }}
+----
+
+By default, the AsciiDoc content is parsed as a full AsciiDoc document.
+If the content represents a single paragraph, and you only want to perform inline substitutions on that content, add the `inline` doctype as the filter's first argument:
+
+----
+{{ post.excerpt | asciidocify: 'inline' }}
+----
+
+TIP: 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).
+
+=== Generating a Table of Contents
+
+Since version 2.1.0 of this plugin, if you're using Jekyll 3 or better, you can use the `tocify_asciidoc` filter to generate a table of contents from the content of any page that is generated from AsciiDoc.
+This filter gives you the ability to place this table of contents anywhere inside the page layout, but outside the main content.
+
+You apply the `tocify_asciidoc` filter to `page.document`, the page variable that resolves to the parsed AsciiDoc document, as shown here:
+
+----
+{{ page.document | tocify_asciidoc }}
+----
+
+The number of section levels (i.e., depth) shown in the table of contents defaults to the value defined by the `toclevels` attribute in the AsciiDoc document.
+To tune the number of levels, pass a numeric value as the filter's first argument.
+
+----
+{{ page.document | tocify_asciidoc: 3 }}
+----
+
+When you use the `tocify_asciidoc` filter, you'll also want to disable the `toc` attribute in your document.
+You can do this using a conditional preprocessor directive.
+
+[source,asciidoc]
+----
+= Guide
+ifndef::env-site[:toc: left]
+
+== Section A
+
+content
+
+== Section B
+
+content
+----
+
 == Customizing the Generated HTML
 
 You can use templates to customize the HTML output that Asciidoctor generates for your site.
@@ -462,7 +660,7 @@ Now run the `bundle` command to install the new gems.
 
 === Step {counter:step}: Create a Templates Folder
 
-Next, create a new folder in your site named [path]__templates_ to store your templates.
+Next, create a new folder in your site named [.path]__templates_ to store your templates.
 
  $ mkdir _templates
 
@@ -481,7 +679,7 @@ asciidoctor:
 
 The final step is to compose a template.
 We'll be customizing the unordered list node.
-Name the file [path]_ulist.html.slim_.
+Name the file [.path]_ulist.html.slim_.
 
 .ulist.html.slim
 [source,slim]
@@ -508,33 +706,82 @@ The next time you build your site, Asciidoctor will use your custom template to
 
 TIP: You can find additional examples of custom templates in the {uri-asciidoctor-backends}[asciidoctor-backends] repository.
 
+== Enabling Asciidoctor Extensions
+
+You enable Asciidoctor extensions in much the same way as this plugin.
+You just need to get Jekyll to load the source.
+
+If the extension you want to use is published as a gem, and you're using Bundler to manage the dependencies for your project (as recommended), then you simply add the gem to the `jekyll_plugins` group in your [.path]_Gemfile_:
+
+[source,ruby]
+----
+group :jekyll_plugins do
+  gem 'asciidoctor-extension-xyz'
+end
+----
+
+Then, run the `bundle` command from Bundler to install the gem:
+
+ $ bundle
+
+If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually.
+Once that's done, add the gem to the list gems for Jekyll to load in your site's {path-config} file:
+
+[source,ruby]
+----
+gems:
+  - asciidoctor-extension-xyz
+----
+
+If the extension you want to use is not published as a gem, or is something you're developing, then you'll load it like an ad-hoc Jekyll plugin.
+Add the file [.path]_asciidoctor-extensions.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/asciidoctor-extensions.rb
+[source,ruby]
+----
+require 'asciidoctor/extensions'
+
+Asciidoctor::Extensions.register do
+  treeprocessor do
+    process do |doc|
+      doc
+    end
+  end
+end
+----
+
+Asciidoctor will automatically enable the extensions in this file when it is loaded by Jekyll.
+
+For a concrete example of using an Asciidoctor extension, refer to the next section.
+
 == 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, {uri-graphviz}[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
+IMPORTANT: For Graphviz and PlantUML diagram generation, {uri-graphviz}[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
+
+TIP: To follow a start-to-finish tutorial that covers how to integrate Asciidoctor Diagram, see https://gist.github.com/mojavelinux/968623c493190dd61c059c2d85f9bdc3[this gist].
 
 === Installation
 
 Using Bundler::
 +
 --
-Add `asciidoctor-diagram` gem to your [path]_Gemfile_:
+Add the `asciidoctor-diagram` gem to your [.path]_Gemfile_:
 
 [source,ruby,subs=attributes+]
 ----
 group :jekyll_plugins do
-  gem 'asciidoctor-diagram', '~> 1.4.0' #{conum-guard}<1>
+  gem 'asciidoctor-diagram', '~> 1.5.4' #{conum-guard}<1>
   gem 'jekyll-asciidoc'
   ...
 end
 ----
 <1> Customize the version of Asciidoctor Diagram as needed.
 
-Then, run the Bundler command to install it:
+Then, run Bundler's install command to install the new gem:
 
  $ bundle install
 --
@@ -570,7 +817,9 @@ asciidoctor:
   safe: unsafe
 ----
 
-With this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., into the same directory).
+With this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., in the same directory) within the destination folder.
+
+WARNING: Jekyll will *delete* the images Asciidoctor Diagram generates unless you follow the instructions in <<Preserving Generated Images>>.
 
 You can use the following example to test your setup:
 
@@ -601,13 +850,15 @@ asciidoctor:
     imagesdir: /images
 ----
 
-With this configuration, all images will be generated into the [path]_images_ directory inside the destination folder.
+With this configuration, Asciidoctor Diagram will generate images into the [.path]_images_ directory within the destination folder.
+
+WARNING: Jekyll will *delete* the images Asciidoctor Diagram generates unless you follow the instructions in <<Preserving Generated Images>>.
 
 ==== Preserving Generated Images
 
-Since Asciidoctor Diagram writes to the output folder, you have instruct Jekyll not to remove these generated files.
+Since Asciidoctor Diagram writes to the output folder, you have to instruct Jekyll not to remove these generated files in the middle of the build process.
 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:
+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]
@@ -621,7 +872,8 @@ An alternative to the monkeypath approach is to identify folders that contain ge
 
 [source,yaml]
 ----
-keep_files: [images]
+keep_files: 
+  - images
 asciidoctor:
   base_dir: :docdir
   safe: unsafe
@@ -644,8 +896,8 @@ The Jekyll AsciiDoc plugin converts AsciiDoc to embeddable HTML.
 This HTML is then inserted into the page layout.
 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:
+. 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]
 ----
@@ -655,7 +907,18 @@ You need to augment the layout to include resources typically present in a stand
 === 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.
+This integration is separate from the Pygments integration in Jekyll 2.
+
+To enable Pygments, you must install the `pygments.rb` gem.
+This gem is bundled with Jekyll 2, so no further action is needed when if you're using Jekyll 2.
+To use Pygments with Ruby >= 2.4 or JRuby, you must install pygments.rb >= 1.1.0, which also requires Jekyll >= 3.0.0.
+If you're using Jekyll 3, add the `pygments.rb` gem to your [.path]_Gemfile_:
+
+[source,ruby]
+----
+gem 'pygments.rb', '~> 1.1.2'
+----
+
 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
 
@@ -688,16 +951,16 @@ NOTE: It may still be necessary to make some tweaks to your site's stylesheet to
 
 === 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:
+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.
+NOTE: You can also link to a local copy of Font Awesome.
 
-Next, you need to add the following CSS rules from the default Asciidoctor stylesheet to the [path]_css/asciidoc.css_ file:
+Next, you need to add the following CSS rules from the default Asciidoctor stylesheet to the [.path]_css/asciidoc.css_ file:
 
 [source,css]
 ----
@@ -778,72 +1041,60 @@ asciidoctor:
     - iconsdir=/images/icons
 ----
 
-Then, simply put the icon images that the page needs in the [path]_images/icons_ directory.
-
-== Converting AsciiDoc in Templates
+Then, simply put the icon images that the page needs in the [.path]_images/icons_ directory.
 
-Jekyll uses the Liquid templating language to process templates.
-This plugin defines an additional filter named `asciidocify` for converting a string of AsciiDoc.
+== Publishing Your Site
 
-Let's assume the excerpt of the post is written in AsciiDoc.
-You can convert it in your template as follows:
+This section covers several options you have available for publishing your site, including GitHub Pages and GitLab Pages.
 
-----
-{{ 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
+=== Using this Plugin on GitHub Pages
 
 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.
 
 [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.
-====
 
 _But don't despair!_
 You can still automate publishing of the generated site to GitHub Pages using a continuous integration job.
 Refer to the http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html[Automate GitHub Pages publishing with Jekyll and Travis CI^] tutorial to find step-by-step instructions.
 You can also refer to the https://github.com/johncarl81/transfuse-site[Transfuse website build^] for an example in practice.
 
-TIP: When using this setup, don't forget to add the [path]_.nojekyll_ file to the root of the source to tell GitLab Pages not to waste time running Jekyll again on the server.
+TIP: When using this setup, don't forget to add the [.path]_.nojekyll_ file to the root of the source to tell GitLab Pages not to waste time running Jekyll again on the server.
 
-=== Jekyll AsciiDoc Quickstart
+==== Jekyll AsciiDoc Quickstart
 
 If you want to take a shortcut that skips all the steps in the previously mentioned tutorial, clone the {uri-jaq}[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
 JAQ includes a Rake build that is preconfigured to deploy to GitHub Pages from Travis CI and also provides a theme (page layout and CSS) that properly styles body content generated from AsciiDoc.
 
-== Using this Plugin on GitLab Pages
+==== Feeling Responsive
+
+If you're looking for a Jekyll theme that provides comprehensive and mature styles and layouts out of the box, check out the https://github.com/Phlow/feeling-responsive[Feeling Responsive] theme.
+It includes integration with this plugin, which you simply have to enable.
+Refer to the https://phlow.github.io/feeling-responsive/getting-started/[Getting Started] page for a step-by-step guide to get your site started and feeling responsive.
+
+=== 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].
+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]. 
+More in-depth information regarding setting up your repository for GitLab Pages can be found in the  https://docs.gitlab.com/ee/pages/README.html[GitLab Enterprise Edition / Pages] documentation.
 
 Assuming the following are true:
 
-. The source of your site resides on the master branch.
+. The source of your site resides on the master branch (though you can use any branch for this purpose).
 . 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.
+You can then 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: 
+  paths:
     - .bundle
 before_script:
   - bundle --path .bundle/gems
@@ -859,7 +1110,7 @@ pages:
 
 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.
+You also need to add an 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+]
@@ -870,10 +1121,13 @@ 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.
+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.
+In this case, update the [.path]__config-gitlab.yml_ file with the appropriate values.
+
+CAUTION: At this time, GitLab Pages only works with projects hosted at GitLab.com or on self-hosted GitLab Enterprise Edition instances.
+GitLab Community Edition does not support continuous integration and cannot host pages.
 
 == Getting Help
 
@@ -924,7 +1178,7 @@ Next, switch to the project directory.
 
 === Install the Dependencies
 
-The dependencies needed to develop the Jekyll AsciiDoc plugin are defined in the [path]_Gemfile_ at the root of the project.
+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:
@@ -944,7 +1198,7 @@ IMPORTANT: Since we've installed dependencies inside the project, it's necessary
 === Running the Tests
 
 The tests are based on RSpec.
-The test suite is located in the [path]_spec_ directory.
+The test suite is located in the [.path]_spec_ directory.
 
 You can run the tests using Rake.
 
@@ -991,12 +1245,23 @@ 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).
+// QUESTION are we sure chained method calls should be an exception?
 
 * Don't indent `when` lines in a case block.
 
+* Wrap API docs at 120 characters.
+
+* Leave a single space inside brackets of a Hash.
+
+  { "key" => "value" }
+
+* Use JSON-style key-value pair when key is a Symbol.
+
+  { key: "value" }
+
 * Fully qualify the class name (beginning with `::`) of any type not in the current namespace.
 
-  ::File.extname path 
+  ::File.extname path
 
 * Use triple equals to check for type, placing the type on the left hand side.
 
@@ -1017,9 +1282,14 @@ The coding style is as follows:
   end
 
 * For chained method calls, wrap parentheses around nested method call.
+  (NOTE: This produces a warning in Ruby < 2).
 
   asciidoctor_config.replace (Utils.symbolize_keys asciidoctor_config)
 
+* Add `%r` prefix to inline regexp when used as the first argument of a method.
+
+  files.grep %r/^spec\//
+
 * Use parentheses outside of a method call when parentheses are required.
 
   layout = collection_name ? (collection_name.chomp 's') : 'page'
@@ -1044,21 +1314,32 @@ The coding style is as follows:
 
   if (imagesdir = attrs['imagesdir'])
 
-* Use simple check for nil.
+* Use variable reference to check for nil.
 
-  if base 
+  if base
 
 * Use `%()` instead of double quotes around interpolated strings.
 
   %(--- #{val})
 
+* Use single quotes around string if interpolation is not required.
+
+  'asciidoctor'
+
 * Name constants using pascal style.
 
   NewLine = %(\n)
 
-* Store each static regular expression in a constant.
+* Define each static regular expression (regexp) as a constant so it's precompiled.
+  Append `Rx` suffix to name.
+
+  ExtensionRx = /^\.adoc$/
+
+* Place the regular expression (regexp) before the string when creating a match.
 
-  HeaderBoundaryRx = /(?<=\p{Graph})\n\n/
+  ExtensionRx =~ ext
++
+  ExtensionRx.match ext
 
 * Use parentheses in traditional style when writing test assertions.
 
@@ -1066,6 +1347,31 @@ The coding style is as follows:
   expect(result.key? 'icons').to be true
   expect(contents).to match('<div class="page-content">')
 
+* Use `.size` to get the length of a collection and `.length` to get the length of a string.
+
+  "abc".length
+  [1, 2, 3].size
+
+* Use `+#[0]+` and `+#[-1]+` to get the first and last element of an Array, respectively, rather than `#first` and `#last`.
+  NOTE: You still have to use `#first` and `#last` on an Enumerable object that's not an Array.
+
+  a = [1, 2, 3]
+  a[0]
+  a[-1]
+
+* Pass symbol reference to `.map` when invoking no-args method on iteration variable (parens are required).
+
+  lines.map(&:strip)
+
+* When calling `raise` to raise an exception, pass the exception class as the first argument and the message as the second.
+  Write the message as a sentence, but exclude the period.
+
+  raise ::ArgumentError, 'Not a valid argument'
+
+* Use name instead of symbol to alias a method.
+
+  alias copy original
+
 ////
 * use `do; end` for multi-line blocks; use `{}` for single-line blocks
 * try to make assignments in condition if scoped to that block
@@ -1074,7 +1380,7 @@ The coding style is as follows:
 
 === Releasing the Gem
 
-When you are ready for a release, first set the version in the file [path]_lib/jekyll-asciidoc/version.rb_.
+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:
 
  Release X.Y.Z
@@ -1100,7 +1406,7 @@ This plugin was created by Dan Allen and Paul Rayner and has received contributi
 
 === Copyright and License
 
-Copyright (C) 2013-2016 Dan Allen, Paul Rayner, and the Asciidoctor Project.
+Copyright (C) 2013-2017 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.