jekyll-asciidoc 2.1.1 → 3.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 700e623dddf15c30365dc58b3a9c59edaba9d852682d03436e10442e1edc8627
-  data.tar.gz: 3a3daa57c865884b73bf6dfdc4002381954adb3d284905d67dea1840d9597806
+  metadata.gz: df9c038b47a511b9b26c4c9e8f585f5d6e89b747f47cfa09f2e257edb26e73bf
+  data.tar.gz: 86591c6545adce1715f2f3afd5032671748e33013ccc567599bd0362101ae9aa
 SHA512:
-  metadata.gz: 9307232a92356f4a83f73b0b40f2ab919dabf3c7c05351ba6f27e9f7fda2e9ba3e5d2d012d7531dd9d4282c5d8360619bd915aa44217fc63e1b0dee54167b9fd
-  data.tar.gz: 431a2f10d4871ed4db7465620a25eb617e90196d5ff481ba9a7676df462ac0772be216222db05dc67ad5f3412a7658869f0c55701b82c45bdd0b53006d1d07a0
+  metadata.gz: 5afb33673bed24e8448ab7cb4def0a6cb3606c9bdc0d69ac6dac15c374f6aa17de50a765416447699486765c5ffefaf9b5323c0e1af282e64f08956c001fbeef
+  data.tar.gz: 7d5dbf5562d3c260555947dc264287693f5bedcf36e51e0fa63a93875013bce949f9545ddf7d318ce6485e86bae01dd2587f917ac87b00868c4da1edc7a60cb2

data/CHANGELOG.adoc

@@ -5,6 +5,32 @@
 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.
 
+== 3.0.0.beta.1 (2018-12-29) - @mojavelinux
+
+* only support Ruby >= 2.2.0 and Jekyll >= 3.0.0
+* update tests to only run against supported versions
+* load processor eagerly (at end of plugin initialization)
+* don't crash if document body is empty (#179)
+* process AsciiDoc header if page has only an AsciiDoc header but no body
+* honor layout defined in frontmatter defaults (#187)
+* allow page layout to be soft set in site config (#193)
+* set asciidoc property to true on all AsciiDoc pages (#189)
+* set asciidoc property to true on any (AsciiDoc) page enriched by this plugin (i.e., page.asciidoc) (#189)
+* don't call nil_or_empty? outside of an Asciidoctor context (#142)
+* don't delete category and tag; sync w/ first entry in array of matching property (#160)
+* don't coerce a falsy value of page-layout defined in _config.yml to nil
+* integrate collections that are not written (output flag is set to false) (#161)
+* document how to enable STEM support (#163)
+* document that a liquid tag that includes HTML must be enclosed in a passthrough block (#180)
+* document that page attributes must be defined in the document header (#172)
+* document both the plugins and gems config keys and when to use one vs the other (#159)
+* document how to disable publishing for a page
+* document how to make a draft post
+* recommend installing gems into project and using a .ruby-version file
+* pass standalone option through data instead of prepending to content
+* set up code coverage reports (#196)
+* set up code linter (Rubocop) (#201)
+
 == 2.1.1 (2018-11-08) - @mojavelinux
 
 * honor layout defined in frontmatter defaults (#187)

data/Gemfile

@@ -1,20 +1,8 @@
 source 'https://rubygems.org'
 gemspec
 
-gem 'jekyll', %(~> #{ENV['JEKYLL_VERSION']}) if ENV.key? 'JEKYLL_VERSION'
+gem 'jekyll', %(~> #{ENV['JEKYLL_VERSION']}), require: false if ENV.key? 'JEKYLL_VERSION'
+gem 'pygments.rb', '~> 1.2.1', require: false
+gem 'rubocop', '~> 0.61.1', require: false
 # NOTE Windows does not include zoneinfo files, so load tzinfo-data gem
-gem 'tzinfo-data', platform: :mingw
-
-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
+gem 'tzinfo-data', platform: [:x64_mingw, :mingw], require: false

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2013-2017 Dan Allen, Paul Rayner, and the Asciidoctor Project
+Copyright (C) 2013-2018 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,7 +1,6 @@
 = Jekyll AsciiDoc Plugin (powered by Asciidoctor)
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Paul Rayner <https://github.com/paulrayner[@paulrayner]>
-v2.1.1, 2018-11-08
-v2.1.0, 2017-05-21
+v3.0.0.beta.1, 2018-12-29
 // Settings:
 :idprefix:
 :idseparator: -
@@ -60,16 +59,18 @@ image:https://img.shields.io/travis/asciidoctor/jekyll-asciidoc/master.svg[Build
 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 the {uri-asciidoc}[AsciiDoc] source files in your site to HTML pages using {uri-asciidoctor}[Asciidoctor].
+A plugin for {uri-jekyll}[Jekyll] (>= 3.0.0) that converts {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]
+{uri-repo}/tree/v2.1.x#readme[2.1.x]
 &hybull;
-{uri-repo}/tree/1.1.x#readme[1.1.x]
+{uri-repo}/tree/v2.0.x#readme[2.0.x]
 &hybull;
-{uri-repo}/tree/1.0.x#readme[1.0.x]
+{uri-repo}/tree/v1.1.x#readme[1.1.x]
+&hybull;
+{uri-repo}/tree/v1.0.x#readme[1.0.x]
 endif::[]
 
 toc::[]
@@ -88,10 +89,20 @@ These attributes are merged with the page variables defined in the front matter
 
 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).
+* `tocify_asciidoc` -- Generates a table of contents in HTML from the parsed AsciiDoc document of the current page (since 2.1.0).
 
 These extensions are registered automatically when the [.app]*jekyll-asciidoc* gem is required.
 
+== Prerequisites
+
+To use this plugin, you must be using Jekyll >= 3.0.0 and Ruby >= 2.2.0 (with development headers installed).
+You should also be familiar with creating sites with Jekyll.
+If you're not, you should first read the {uri-jekyll-docs}[Jekyll documentation] to familiarize yourself with how it works.
+Experience with AsciiDoc and Asciidoctor is also helpful, but not a requirement.
+
+Like Jekyll, this plugin was designed for developers, so some assembly is required.
+That means you'll be expected to edit configuration, modify HTML templates, and customize CSS to use it fully.
+
 == Installation
 
 This plugin is packaged as a gem named [.app]*{uri-gem}[jekyll-asciidoc]* and published to RubyGems.org.
@@ -102,6 +113,9 @@ Your method of installation will depend on whether you use Bundler to manage the
 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.
 
+TIP: If you're using RVM, you should add a [.path]_.ruby-version_ file to the project so your shell automatically switches to the correct version of Ruby each time you enter the project.
+For more information, refer to the the page https://rvm.io/workflow/projects[RVM Project Workflow].
+
 === 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_:
@@ -117,6 +131,17 @@ Then, run the `bundle` command from Bundler to install the gem:
 
  $ bundle
 
+Jekyll will automatically activate any plugins listed in the `:jekyll_plugins` group.
+
+If you want to keep the installed gems inside the project, use this command instead:
+
+ $ bundle --path=.bundle/gems
+
+TIP: Subsequent calls to `bundle` will retain the `path` setting.
+
+Keep in mind that the gems Bundler installs are linked to the current version of Ruby.
+If you switch Ruby versions, you'll need to run `bundle` again.
+
 === Manual Installation
 
 If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually:
@@ -128,10 +153,18 @@ To avoid this bad practice, we recommend using RVM (or another Ruby version mana
 
 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]
+----
+plugins:
+- jekyll-asciidoc
+----
+
+If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
+
 [source,yaml]
 ----
 gems:
-  - jekyll-asciidoc
+- jekyll-asciidoc
 ----
 
 == Creating Pages
@@ -142,7 +175,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]
-. _(Optional beginning with version 2.0.0 of this plugin)_ Aside from posts, documents must begin with a {uri-front-matter}[front matter header].
+. While you can use a Jekyll front matter header, it is not required.
 
 Here's a sample AsciiDoc file that meets these criteria:
 
@@ -186,10 +219,28 @@ Any AsciiDoc attribute defined in the AsciiDoc document header whose name begins
 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.
+Since the attribute value is processed as YAML data, you can build nested data structure using the inline YAML syntax.
+For example, here's how you can assign a value to the `page.header.image` page variable:
+
+[source,asciidoc]
+----
+:page-header: { image: logo.png }
+----
+
+To define a page attribute that contains multiple words, use either a hyphen or underscore character to connect the words.
+
+[source,asciidoc]
+----
+:page-short-name: slug
+----
+
+IMPORTANT: Page attributes must be defined in the document header.
+That means either putting them directly below the document title (the line beginning with a single equals sign in the sample above) or above all other AsciiDoc content if the document title is not defined in AsciiDoc.
+The AsciiDoc document header stops after the first blank line.
+For more details about the document header, see the http://asciidoctor.org/docs/user-manual/#doc-header[Document Header] chapter in the Asciidoctor User Manual.
 
-TIP: Use either a hyphen or an underscore as a separator for page attributes with multiple words (e.g., page-short-name).
+IMPORTANT: You may use include directives in the the document header.
+However, you must ensure that the file included _does not_ contain blank lines.
 
 === Specifying a Layout
 
@@ -207,16 +258,69 @@ To review, here are the different ways to specify a layout using the AsciiDoc at
 * `: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: ~` or `:page-layout: none` -- don't use a layout or create a standalone HTML document (often produces an HTML fragment); the `~` value only works when defined as an AsciiDoc page attribute; otherwise, the value `none` must be used
+* `:page-layout: none` or `:page-layout: ~` -- don't use a layout or create a standalone HTML document (often produces an HTML fragment); use of the value `~` is discouraged; the value `none` is preferred
+
+=== Disabling Publishing of a Page
+
+To prevent a page from being published, set the page attribute named `page-published` to `false` (which, in turn, sets the page variable named `published` to `false`.
+
+[source,asciidoc]
+----
+= Top Secret Info
+:page-published: false
+
+This page should not be published.
+----
 
 === 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 (aka the document title) (becomes title)
-* id (becomes docid)
+* doctitle (aka the document title) (becomes `title`)
+* id (becomes `docid`)
 * author
-* revdate (becomes date; value is converted to a DateTime object; posts only)
+* revdate (becomes `date`; value is converted to a DateTime object; posts only)
+
+Although not an implicit page variable, another very common page variable to set is `page-description`, which becomes `description` in the model.
+
+==== Showing the Document Title
+
+By default, when Asciidoctor converts your document, it does not include the document title in the body (aka `content`) part of the document that is passed to the layout.
+Instead, it skims off the document title and assigns it to the model as `page.title`.
+If you don't see the document title on the generated page at first, that's normal.
+
+There are two ways to have the document title included in the page:
+
+. Configure the layout to output the document title explicitly
+. Configure Asciidoctor to include the document title in the body
+
+The first option is the most typical.
+Somewhere in your layout, you should include the following statement:
+
+----
+<h1>{{ page.title }}</h1>
+----
+
+This approach gives you the most control over how the document title appears and what HTML is used to enclose it.
+
+If, instead, you want the document title to be included in the body, add the following configuration to your site's {path-config} file:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+  - showtitle=@
+----
+
+It's also possible to enable or override this setting per page.
+
+[source,asciidoc]
+----
+= Page Title
+:showtitle:
+----
+
+Using either of these approaches, the document title will be shown on the generated page.
 
 ==== Giving Your Post the Time of Day
 
@@ -250,9 +354,47 @@ Lorem ipsum.
 
 Note that the revision line must be preceded by the implicit author line.
 
+==== Classifying Your Post
+
+In Jekyll, you classify a post by assigning it to categories and/or tags.
+While you can define them in the front matter, as normal, it's also possible to omit the front matter and assign them in the AsciiDoc header instead.
+
+The AsciiDoc attributes to use to assign categories and tags to your post are `page-categories` and `page-tags`, respectively.
+The attribute value must be expressed using the inline Array syntax for YAML, which is a comma-separated list of items surrounded by square brackets.
+If you only have one item, you can omit the brackets.
+In this case, you can also drop the plural from the attribute name.
+
+[source,asciidoc]
+----
+= Introducing the Jekyll AsciiDoc Plugin
+Author Name
+:page-category: Tech
+:page-tags: [ruby, jekyll, asciidoctor, ssg]
+
+The Jekyll AsciiDoc plugin makes Jekyll awesome.
+Why?
+Because you can write posts like this one in AsciiDoc!
+----
+
+Recall that the value of page attributes is parsed as an inline YAML value.
+
+==== Publishing a Draft Post
+
+You can defer adding a date to a post until it's ready to publish by making it a draft.
+To make a draft post, just place it in the [.path]_{empty}_drafts_ folder instead of the [.path]_posts_ folder.
+But don't include the date in the filename or AsciiDoc header.
+
+To include the drafts when building the site, pass the `--drafts` flag to the `jekyll` command:
+
+ $ jekyll build --drafts
+
+The date of each draft post will be based on the file's last modification time.
+
+When you're ready to publish the post, move the file from the [.path]_{empty}_drafts_ folder to the [.path]_posts_ folder and assign a date to it either by adding it to the filename or by defining the `revdate` attribute in the AsciiDoc header.
+
 === 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).
+Unlike other content files, the {uri-liquid-templates}[Liquid template preprocessor] is not applied to AsciiDoc files by default (since 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]
@@ -264,12 +406,23 @@ IMPORTANT: AsciiDoc files may include a {uri-front-matter}[front matter header]
 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.
+NOTE: Since 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.
 
+If you're using the Liquid include tag to include HTML into the AsciiDoc document, you need to enclose it in a passthrough block.
+
+----
+++++
+{% include file.html %}
+++++
+----
+
+This is necessary since AsciiDoc will escape HTML by default.
+To pass it through as is requires enclosing in a passthrough block.
+
 == Building and Previewing Your Site
 
 You can build your site into the [.path]__site_ directory using:
@@ -285,12 +438,10 @@ You can preview your site at \http://localhost:4000 using:
 
  $ jekyll serve
 
-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:
+The `serve` command monitors the file system and rebuilds the site whenever a change is detected by default (i.e., watch mode).
+To disable watch mode, use the `--no-watch` flag:
 
- $ jekyll serve --watch
-
-To disable watch mode explicitly, use the `--no-watch` flag instead.
+ $ jekyll serve --no-watch
 
 You can also use the `--watch` flag with the `build` command:
 
@@ -396,22 +547,22 @@ idseparator=-
 linkattrs=@
 ....
 
-The following attributes are defined per page:
+The following additional 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}.
+You can pass custom attributes to AsciiDoc, or override default attributes provided by the plugin, 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:
-    - idprefix=_
-    - source-highlighter=pygments
-    - pygments-css=style
+  - idprefix=_
+  - source-highlighter=pygments
+  - pygments-css=style
 ----
 
 or key-value pairs defined as a Hash:
@@ -434,7 +585,26 @@ asciidoctor:
     sectanchors: ''
 ----
 
-You may use attribute references in the attribute value to reference any implicit or already defined attribute.
+By default, an attribute value defined in {path-config} overrides the same attribute set in the front matter or header of a document.
+For example, if you set `page-layout` in {path-config}, you won't be able to set it per page.
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+  - page-layout=false
+----
+
+If you want to allow individual pages to be able to override the attribute, append the charcter `@` to the value in {path-config}:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+  - page-layout=false@
+----
+
+You may use attribute references in the attribute value to reference any attribute that's already defined, including implicit attributes.
 For example, to set the `iconsdir` attribute based on the `imagesdir` attribute, use the following:
 
 [source,yaml]
@@ -445,8 +615,8 @@ asciidoctor:
     iconsdir: '{imagesdir}/icons'
 ----
 
-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.
+CAUTION: If the value begins with an attribute reference, and you're defining the attributes using the Hash syntax, you must enclose the value in quotes.
+There are additional edge cases when the value must be enclosed in quotes, so it's generally recommended to use them.
 
 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):
 
@@ -458,7 +628,7 @@ asciidoctor:
 ----
 
 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.
+One of those options is `base_dir`, which is covered in the next section.
 
 ==== Specifying the Base Directory
 
@@ -488,8 +658,6 @@ asciidoctor:
   ...
 ----
 
-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.
 
@@ -537,16 +705,16 @@ If you want to enable this behavior for AsciiDoc files, add the `hardbreaks-opti
 ----
 asciidoctor:
   attributes:
-    - hardbreaks-option
+  - hardbreaks-option
 ----
 
-If you want to allow individual files to override this setting, then assign the value `@` to the attribute:
+If you still want to allow individual files to be able to override the attribute, append the charcter `@` to the value in the site configuration:
 
 [source,yaml]
 ----
 asciidoctor:
   attributes:
-    - hardbreaks-option=@
+  - 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.
@@ -560,7 +728,7 @@ If you want to use this plugin when running Jekyll in safe mode, you must add th
 [source,yaml]
 ----
 whitelist:
-  - jekyll-asciidoc
+- jekyll-asciidoc
 ----
 
 Safe mode is enabled either through the `--safe` flag:
@@ -601,7 +769,7 @@ TIP: This filter allows you to compose site-wide data in AsciiDoc, such your sit
 
 === 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.
+Since version 2.1.0 of this plugin, 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:
@@ -728,10 +896,18 @@ Then, run the `bundle` command from Bundler to install the gem:
 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]
+----
+plugins:
+- asciidoctor-extension-xyz
+----
+
+If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
+
 [source,ruby]
 ----
 gems:
-  - asciidoctor-extension-xyz
+- 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.
@@ -758,7 +934,7 @@ For a concrete example of using an Asciidoctor extension, refer to the next sect
 == 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*.
+In order to use Asciidoctor Diagram in a Jekyll project successfully, *you must use 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`.
@@ -784,7 +960,7 @@ end
 
 Then, run Bundler's install command to install the new gem:
 
- $ bundle install
+ $ bundle
 --
 
 Without Bundler::
@@ -794,13 +970,22 @@ Install gems manually
 
  $ [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-config} file:
+Then, add the `asciidoctor-diagram` gem to the list of plugins for Jekyll to load in your site's {path-config} file:
+
+[source,yaml]
+----
+plugins:
+- asciidoctor-diagram
+- jekyll-asciidoc
+----
+
+If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
 
 [source,yaml]
 ----
 gems:
-  - asciidoctor-diagram
-  - jekyll-asciidoc
+- asciidoctor-diagram
+- jekyll-asciidoc
 ----
 --
 
@@ -874,7 +1059,7 @@ An alternative to the monkeypath approach is to identify folders that contain ge
 [source,yaml]
 ----
 keep_files: 
-  - images
+- images
 asciidoctor:
   base_dir: :docdir
   safe: unsafe
@@ -882,6 +1067,70 @@ asciidoctor:
     imagesdir: /images
 ----
 
+== Enabling STEM Support
+
+Thanks to Asciidoctor, Jekyll AsciiDoc provides built-in support for processing STEM (Science, Technology, Engineering & Math) equations in your AsciiDoc documents.
+To enable this support, you just need to do a bit of configuration.
+
+=== Activating the STEM processing
+
+The first thing you need to do is activate the STEM processing integration in the processor itself.
+To do that, set the `stem` attribute on the document.
+One way is to set the `stem` attribute in the document header:
+
+[source,asciidoc]
+----
+= Page Title
+:stem:
+----
+
+Alternatively, you can enable it the `stem` attribute globally for all AsciiDoc documents in your site by adding the following to your site's {path-config} file:
+
+[source,yaml]
+----
+asciidoctor:
+  attributes:
+  - stem
+----
+
+To learn more about the built-in STEM integration, see the https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM] chapter in the Asciidoctor User Manual.
+
+=== Adding the STEM assets to the page
+
+Technically, Asciidoctor only prepares the STEM equations for interpretation by https://mathjax.org[MathJax].
+That means you have to load MathJax on any page that contains STEM equations (or all pages, if that's easier).
+To do so requires some customization of the page layout.
+
+First, create the file [.path]__includes/mathjax.html_ and populate it with the following contents:
+
+[source,html]
+----
+<script type="text/x-mathjax-config">
+MathJax.Hub.Config({
+  messageStyle: "none",
+  tex2jax: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    ignoreClass: "nostem|nolatexmath"
+  },
+  asciimath2jax: {
+    delimiters: [["\\$", "\\$"]],
+    ignoreClass: "nostem|noasciimath"
+  },
+  TeX: { equationNumbers: { autoNumber: "none" } }
+});
+</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script>
+----
+
+Then, include this file before the closing `</body>` tag in your page layout.
+
+----
+{% include mathjax.html %}
+----
+
+With that configuration in place, the STEM equations in your AsciiDoc file will be presented beautifully using MathJax.
+
 == Adding Supplemental Assets
 
 Certain Asciidoctor features, such as icons, require additional CSS rules and other assets to work.
@@ -908,18 +1157,17 @@ 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 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_:
+To do so, add the `pygments.rb` gem to your [.path]_Gemfile_:
 
 [source,ruby]
 ----
 gem 'pygments.rb', '~> 1.1.2'
 ----
 
+IMPORTANT: To use Pygments with Ruby >= 2.4 or JRuby, you must install pygments.rb >= 1.1.0.
+
 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
 
@@ -1015,8 +1263,8 @@ or in the site configuration:
 ----
 asciidoctor:
   attributes:
-    - icons=font
-    ...
+  - icons=font
+  ...
 ----
 
 === Image-based Admonition and Inline Icons
@@ -1038,8 +1286,8 @@ or your site configuration:
 ----
 asciidoctor:
   attributes:
-    - icons
-    - iconsdir=/images/icons
+  - icons
+  - iconsdir=/images/icons
 ----
 
 Then, simply put the icon images that the page needs in the [.path]_images/icons_ directory.
@@ -1062,7 +1310,30 @@ You can still automate publishing of the generated site to GitHub Pages using a
 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.
+In fact, if you're using Travis CI, it's even easier than that.
+Travis CI provides a https://docs.travis-ci.com/user/deployment/pages/[deployer for GitLab Pages]!
+Using this deployer, Travis CI can push your generated site to GitHub Pages after a successful build on your behalf, as long as you've completed these steps:
+
+. Create a personal access token on GitHub that has write access to your GitHub repository (public_repo or repo scope)
+. Define the token as a secure variable name GITHUB_TOKEN on the Travis CI settings page for your repository
+. Add a deploy configuration to your CI job configuration
+
+Here's a sample deploy configuration you can use:
+
+[source,yaml]
+----
+deploy:
+  provider: pages
+  github-token: $GITHUB_TOKEN
+  local-dir: _site
+  target-branch: gh-pages
+  skip-cleanup: true
+  keep-history: true
+  on:
+    branch: master
+----
+
+TIP: When using this setup, don't forget to add the [.path]_.nojekyll_ file to the root of the source directory to tell GitHub Pages not to waste time running Jekyll again on the server.
 
 ==== Jekyll AsciiDoc Quickstart
 
@@ -1093,20 +1364,20 @@ You can then use the following [.path]_.gitlab-ci.yml_ file to get starting host
 .gitlab-ci.yml
 [source,yaml]
 ----
-image: ruby:2.3
+image: ruby:2.5
 cache:
   paths:
-    - .bundle
+  - .bundle
 before_script:
-  - bundle --path .bundle/gems
+- bundle --path .bundle/gems
 pages:
   script:
-    - bundle exec jekyll build -d public --config _config.yml,_config-gitlab.yml -q
+  - bundle exec jekyll build -d public --config _config.yml,_config-gitlab.yml -q
   artifacts:
     paths:
-      - public
+    - public
   only:
-    - master
+  - master
 ----
 
 This script runs Jekyll on the official Ruby Docker container.
@@ -1226,158 +1497,65 @@ Then, run RSpec with the `focus` flag enabled:
 
 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).
-// 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
-
-* 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
-
-* 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\//
+=== Generating Code Coverage
 
-* Use parentheses outside of a method call when parentheses are required.
+To generate a code coverage report when running tests using simplecov, set the `COVERAGE` environment variable as follows when running the tests:
 
-  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 variable reference to check for nil.
-
-  if base
-
-* Use `%()` instead of double quotes around interpolated strings.
+ $ COVERAGE=true bundle exec rake spec
 
-  %(--- #{val})
+You'll see a total coverage score as well as a link to the HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
 
-* Use single quotes around string if interpolation is not required.
+Despite being fast, the downside of using simplecov is that it misses branches.
+You can use deep-cover to generate a more thorough report.
+To do so, set the `COVERAGE` environment variable as follows when running the tests:
 
-  'asciidoctor'
+ $ COVERAGE=deep bundle exec rake spec
 
-* Name constants using pascal style.
+You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
 
-  NewLine = %(\n)
-
-* Define each static regular expression (regexp) as a constant so it's precompiled.
-  Append `Rx` suffix to name.
+////
+As an alternative to deep cover's native HTML reporter, you can also use istanbul / nyc.
+First, you'll need to have the `nyc` command available on your system:
 
-  ExtensionRx = /^\.adoc$/
+ $ npm install -g nyc
 
-* Place the regular expression (regexp) before the string when creating a match.
+or
 
-  ExtensionRx =~ ext
-+
-  ExtensionRx.match ext
+ $ yarn global add nyc
 
-* Use parentheses in traditional style when writing test assertions.
+Next, in addition to the `COVERAGE` environment variable, also set the `DEEP_COVER_REPORTER` environment variable as follows when running the tests:
 
-  expect(site.config['asciidoc']['processor']).to eql('asciidoctor')
-  expect(result.key? 'icons').to be true
-  expect(contents).to match('<div class="page-content">')
+ $ COVERAGE=deep DEEP_COVER_REPORTER=istanbul bundle exec rake spec
 
-* Use `.size` to get the length of a collection and `.length` to get the length of a string.
+You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
+////
 
-  "abc".length
-  [1, 2, 3].size
+=== Running the Code Linter
 
-* 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.
+Before you commit code, you should run it through the linter to make sure it adheres to the coding style.
+You can run the linter using the following command:
 
-  a = [1, 2, 3]
-  a[0]
-  a[-1]
+ $ bundle exec rake lint
 
-* Pass symbol reference to `.map` when invoking no-args method on iteration variable (parens are required).
+The coding style is enforced by Rubocop.
+The rules are defined in [.path]_.rubocop.yml_.
+These rules extend from the default rule set provided by Rubocop to match the style of the project.
 
-  lines.map(&:strip)
+=== Installing the Gem Locally
 
-* 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.
+You can install the development version of the gem as follows:
 
-  raise ::ArgumentError, 'Not a valid argument'
+ $ bundle exec rake install
 
-* Use name instead of symbol to alias a method.
+This allows you to use an unreleased version of the gem to build your site.
 
-  alias copy original
+If you want to build the gem and install it yourself, use these commands instead:
 
-////
-* 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`
-////
+ $ bundle exec rake build
+ $ [sudo] gem install pkg/jekyll-asciidoc-*.dev.gem
 
 === Releasing the Gem
 
@@ -1394,7 +1572,7 @@ Next, package, tag and release the gem to RubyGems.org, run the following rake t
 
 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).
+Once you finish the release, you should update the version to the next micro version in the sequence using the `.dev` suffix (e.g., 3.0.1.dev).
 
 == About the Project
 
@@ -1407,7 +1585,7 @@ This plugin was created by Dan Allen and Paul Rayner and has received contributi
 
 === Copyright and License
 
-Copyright (C) 2013-2017 Dan Allen, Paul Rayner, and the Asciidoctor Project.
+Copyright (C) 2013-2018 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.