jekyll_plugin_support 0.7.2 → 0.8.1

data/README.md

@@ -1,155 +1,182 @@
 # `jekyll_plugin_support` [![Gem Version](https://badge.fury.io/rb/jekyll_plugin_support.svg)](https://badge.fury.io/rb/jekyll_plugin_support)
 
-`Jekyll_plugin_support` is a Ruby gem that facilitates writing and testing Jekyll plugins.
+`Jekyll_plugin_support` is a Ruby gem that provides a framework for writing and testing Jekyll plugins.
+
+`Jekyll_plugin_support` can be used to create simple Jekyll plugins in
+the `_plugins/` directory of your Jekyll project, or gem-based Jekyll plugins.
+
 At present, only Jekyll tags and blocks are supported.
 
+Plugins that use `jekyll_plugin_support` include:
 
-## Installation
+<ul style="columns: 2">
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_all_collections'><code>jekyll_all_collections</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_badge'><code>jekyll_badge</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_emoji'><code>jekyll_emoji</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_flexible_include.html'><code>jekyll_flexible_include</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_href.html'><code>jekyll_href</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_img.html'><code>jekyll_img</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_plugin_template.html'><code>jekyll_plugin_template</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_outline.html'><code>jekyll_outline</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_pre.html'><code>jekyll_pre</code></a></li>
+  <li><a href='https://www.mslinn.com/jekyll_plugins/jekyll_quote.html'><code>jekyll_quote</code></a></li>
+</ul>
 
-`Jekyll_plugin_support` can be used to create simple Jekyll plugins in the `_plugins/` directory, or gem-based Jekyll plugins.
+... and also the demonstration plugins in
+[`jekyll_plugin_support`](https://github.com/mslinn/jekyll_plugin_support/tree/master/demo/_plugins)
 
-### Simple Plugins
 
-For jekyll plugins defined in the `_plugins/` directory,
-add this line to your Jekyll plugin's `Gemfile`:
+## Installation
+
+`Jekyll_plugin_support` is packaged as a Ruby gem.
+If your project is a custom plugin that will reside in a Jekyll project’s `_plugins` directory,
+add the following line to your Jekyll plugin’s `Gemfile`.
 
 ```ruby
 group :jekyll_plugins do
-  gem 'jekyll_plugin_support'
+  ...
+  gem 'jekyll_plugin_support', '>= 0.8.0'
+  ...
 end
 ```
 
-And then execute:
+Otherwise, if your custom plugin will be packaged into a gem, add the following to your plugin’s `.gemspec`:
 
-```shell
-$ bundle
+```ruby
+Gem::Specification.new do |spec|
+  ...
+  spec.add_dependency 'jekyll_plugin_support', '>= 0.8.0'
+  ...
+end
 ```
 
+Install the `jekyll_plugin_support` Ruby gem and mark it as a dependency of your project by typing:
 
-### Gem-Based Plugins
+  ```shell
+  $ bundle
+  ```
 
-Add this line to your Jekyll plugin's `.gemspec`:
+Copy the CSS classes from `demo/assets/css/jekyll_plugin_support.css` to your Jekyll project&rsquo;s CSS file.
 
-```ruby
-spec.add_dependency 'jekyll_plugin_support'
-```
 
-And then execute:
+## About `jekyll_plugin_support`
 
-```shell
-$ bundle
-```
+`JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag`
+provide support for [Jekyll tag block plugins](https://jekyllrb.com/docs/plugins/tags/#tag-blocks)
+and [Jekyll inline tag plugins](https://jekyllrb.com/docs/plugins/tags/), respectively.
+They are very similar in construction and usage.
+
+Instead of subclassing your custom Jekyll block tag class from `Liquid::Block`,
+subclass from `JekyllSupport::JekyllBlock`.
+Similarly, instead of subclassing your custom Jekyll tag class from `Liquid::Tag`,
+subclass from `JekyllSupport::JekyllTag`.
+
+Both JekyllSupport classes instantiate new instances of
+[`PluginMetaLogger`](https://github.com/mslinn/jekyll_plugin_logger) (called `@logger`) and
+[`JekyllPluginHelper`](https://github.com/mslinn/jekyll_plugin_support/blob/master/lib/jekyll_plugin_support_helper.rb)
+(called `@helper`).
+
+`JekyllPluginHelper` defines a generic initialize method, and your tag or block tag class should not need to override it.
+Also, your tag or block tag class should not define a method called render, because `jekyll_plugin_support` defines one.
+
+Instead, define a method called `render_impl`.
+For inline tags, `render_impl` does not accept any parameters.
+For block tags, a single parameter is required, which contains text passed from your block in the page.
+
+Your implementation of render_impl can parse parameters passed to the tag / block tag, as described in
+[Tag Parameter Parsing](http://mslinn.com/jekyll/10100-jekyll-plugin-background.html#params).
+
+The following variables are predefined within `render`.
+See the [Jekyll documentation](https://jekyllrb.com/docs/variables/) for more information.
+
+* `@argument_string` – Original unparsed string from the tag in the web page
+* `@config` – Jekyll [configuration data](https://jekyllrb.com/docs/configuration/)
+* `@layout` – Front matter specified in layouts
+* `@mode` – [possible values](https://jekyllrb.com/docs/configuration/environments/)
+  are `development`, `production`, or `test`
+* `@page` – Jekyll [page variable](https://jekyllrb.com/docs/variables/#page-variables)
+* `@paginator` – Only has a value when a paginator is active; they are only available in index files.
+* `@site` – Jekyll [site variable](https://jekyllrb.com/docs/variables/#site-variables)
+* `@tag_name` – Name of the inline tag or block plugin
+* `@theme` – Theme variables (introduced in Jekyll 4.3.0)
 
 
 ## General Usage
 
+Please see the [`demo/`](demo/) project for a well-documented set of demonstration Jekyll plugins that are built from `jekyll_plugin_support`.
+Additional information is available [here](https://mslinn.com/jekyll/10200-jekyll-plugin-background.html) and the
+[`jekyll_plugin_support`](https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html) documentation.
+
 `JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag`
-provide support for Jekyll tag blocks and Jekyll tags, respectively.
-They are very similar in construction and usage.
+provide support for Jekyll block tags and Jekyll inline tags, respectively.
+They are similar in construction and usage.
 
 Instead of subclassing your Jekyll block tag class from `Liquid::Block`,
 subclass from `JekyllSupport::JekyllBlock` instead.
 
-Similarly, instead of subclassing your Jekyll tag class from `Liquid::Tag`,
+Likewise, instead of subclassing your Jekyll inline tag class from `Liquid::Tag`,
 subclass from `JekyllSupport::JekyllTag` instead.
 
 Both `JekyllSupport` classes instantiate new instances of
 [`PluginMetaLogger`](https://github.com/mslinn/jekyll_plugin_logger) (called `@logger`) and
-[`JekyllPluginHelper`](lib/jekyll_plugin_support_helper.rb) (called `@helper`).
+[`JekyllPluginHelper`](lib/jekyll_plugin_helper.rb) (called `@helper`).
+
+
+### Inline and Block Tag Plugin Implementation
+
+Both `JekyllSupport` classes define a generic `initialize` method,
+and your inline tag or block tag class should not override it.
+
+Also, your inline tag or block tag class should not define a method called `render`,
+because both `JekyllSupport` classes define this method.
 
-`JekyllPluginHelper` defines a generic `initialize` method,
-and your tag or block tag class should not override it.
-Also, your tag or block tag class should not define a method called `render`,
-because `JekyllBlock.initialize` defines one, which creates variables called
-[`@page`](https://jekyllrb.com/docs/variables/#page-variables) and
-[`@site`](https://jekyllrb.com/docs/variables/#site-variables).
 
 Instead, define a method called `render_impl`.
-For tags, `render_impl` does not accept any parameters.
+For inline tags, `render_impl` does not accept any parameters.
 For block tags, a single parameter is required, which contains any text enclosed within your block.
 
-Your implementation of `render_impl` can access `@page` and `@site`,
-and can parse parameters passed to the tag / block tag, [as described here](https://mslinn.com/jekyll/10100-jekyll-plugin-background.html#params):
 
-### For a tag:
+## Predefined Plugin Variables
 
-```ruby
-require 'jekyll_plugin_support'
+`Jekyll_plugin_support` defines the following Ruby variables that you can use in your plugin&rsquo;s `render_impl` method:
 
-module Jekyll
-  class MyTag < JekyllSupport::JekyllTag
-    VERSION = '0.1.0'.freeze
+* `@argument_string` Unparsed markup passed as a parameter to your block tag and inline tag.
 
-    def render_impl
-      my_output = "<p>blah blah</p>"
-      <<~END_OUTPUT
-        #{my_output}
-      END_OUTPUT
-    end
+* [`@attribution`](#subclass-attribution) Attribution markup
 
-    JekyllPluginHelper.register(self, 'demo_tag')
-  end
-end
-```
+* [`@config`](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site)
+  [YAML](https://yaml.org/) Jekyll site configuration file
 
-### For a tag block:
+* [`@helper`](https://github.com/mslinn/jekyll_plugin_support/blob/master/lib/jekyll_plugin_helper.rb)
+  `JekyllPluginHelper` instance for your plugin.
 
-```ruby
-require 'jekyll_plugin_support'
-
-module Jekyll
-  class MyBlock < JekyllSupport::JekyllBlock
-    VERSION = '0.1.0'.freeze
-
-    def render_impl(content)
-      @helper.gem_file __FILE__ # Enables attribution
-      my_output = "<p>blah blah</p>"
-      <<~END_OUTPUT
-        #{my_output}
-        #{@helper.attribute if @helper.attribution}
-      END_OUTPUT
-    end
-
-    JekyllPluginHelper.register(self, 'demo_block')
-  end
-end
-```
+* [`@layout`](https://jekyllrb.com/docs/variables/#global-variables) Layout information
 
-Note that each tag or tag block must define a constant called `VERSION`.
-If your plugin is packaged as a gem, then you might need to include `version.rb` into the plugin class.
-For example, if `lib/my_plugin/version.rb` looks like this:
+* [`@logger`](jekyll_plugin_logger) `jekyll_plugin_logger` instance for your Jekyll plugin.
 
-```ruby
-module MyPluginVersion
-  VERSION = '0.5.1'.freeze
-end
-```
+* [`@mode`](https://jekyllrb.com/docs/configuration/environments/)
+  Indicates `production` or `development` mode.
 
-Then your plugin can incorporate the `VERSION` constant into your plugin like this:
+* [`@page`](https://jekyllrb.com/docs/variables/#page-variables) Page variables
+
+* [`@paginator`](https://jekyllrb.com/docs/variables/#page-variables) Pagination variables
+
+* [`@scopes`](https://jekyllrb.com/docs/variables/)
+  See the [`jekyll_plugin_support` demo project](demo/variables.html)
+
+* [`@site`](https://jekyllrb.com/docs/variables/#site-variables) Site variables
+
+* [`@tag_config`](lib/jekyll_plugin_support_tag.rb)
+  Contents of the section of `_config.yml` named after your plugin.
+
+* `@tag_name` Name of your Jekyll block tag or inline tag plugin.
+
+* [`@theme`](https://jekyllrb.com/docs/variables/#global-variables) Theme variables
+
+* `text` Content provided to your block tag.
 
-```ruby
-require 'jekyll_plugin_support'
-require_relative 'my_block/version'
-
-module Jekyll
-  class MyBlock < JekyllSupport::JekyllBlock
-    include MyPluginVersion
-
-    def render_impl(text)
-      @helper.gem_file __FILE__ # Enables attribution
-      my_output = "<p>blah blah</p>"
-      <<~END_OUTPUT
-        #{my_output}
-        #{@helper.attribute if @helper.attribution}
-      END_OUTPUT
-    end
-
-    JekyllPluginHelper.register(self, 'demo_tag')
-  end
-end
-```
 
-### Argument Parsing
+## Argument Parsing
 
 Tag arguments can be obtained within `render_impl`.
 Both keyword options and name/value parameters are supported.
@@ -158,24 +185,29 @@ Both `JekyllTag` and `JekyllBlock` use the standard Ruby mechanism for parsing c
 [`shellwords`](https://ruby-doc.org/stdlib-2.5.1/libdoc/shellwords/rdoc/Shellwords.html) and
 [`key_value_parser`](https://www.rubydoc.info/gems/key-value-parser).
 
-All your code has to do is to specify the keywords to search for in the string passed from the HTML page that your tag is embedded in.
-The included `demo` website has examples; both [`demo/_plugins/demo_tag.rb`](demo/_plugins/demo_tag.rb) and
-[`demo/_plugins/demo_block.rb`](demo/_plugins/demo_block.rb) contain the following:
+All your code has to do is to specify the keywords to search for in the string
+passed from the HTML page that your tag is embedded in.
+The included `demo` website has examples;
+both [`demo/_plugins/demo_inline_tag.rb`](demo/_plugins/demo_inline_tag.rb) and
+[`demo/_plugins/demo_block_tag.rb`](demo/_plugins/demo_block_tag.rb) contain the following:
 
 ```ruby
 @keyword1  = @helper.parameter_specified? 'keyword1'
 @keyword2  = @helper.parameter_specified? 'keyword2'
-@name1  = @helper.parameter_specified? 'name1'
-@name2  = @helper.parameter_specified? 'name2'
+@name1     = @helper.parameter_specified? 'name1'
+@name2     = @helper.parameter_specified? 'name2'
 ```
 
-In [`demo/index.html`](demo/index.html), the following invoked the tag:
+
+### Example
+
+[`demo/index.html`](demo/index.html), contains the following inline tag invocation:
 
 ```html
-{% demo_tag keyword1 name1='value1' unreferenced_key unreferenced_name="unreferenced_value" %}
+{% demo_inline_tag keyword1 name1='value1' unreferenced_key unreferenced_name="unreferenced_value" %}
 ```
 
-The `demo/_plugins/demo_tag.rb` plugin uses `@helper.parameter_specified?` provided by
+The `demo/_plugins/demo_inline_tag.rb` plugin uses `@helper.parameter_specified?` provided by
 `jekyll_support_plugin` to parse the string passed to the tag, which is
 `keyword1 name1='value1' unreferenced_key unreferenced_name="unreferenced_value"`.
 
@@ -185,7 +217,12 @@ The `demo/_plugins/demo_tag.rb` plugin uses `@helper.parameter_specified?` provi
     that name/value pair is removed from the argument string.
 * The remainder of the argument string is now `unreferenced_key unreferenced_name="unreferenced_value"`.
 
-Name/value parameters can be quoted; if the value consists of only one token then it does not need to be quoted.
+
+### To Quote Or Not To Quote
+
+Parameter values can be quoted.
+
+If the value consists of only one token then quoting is optional.
 The following name/value parameters all have the same result:
 
 * `pay_tuesday="true"`
@@ -193,18 +230,117 @@ The following name/value parameters all have the same result:
 * `pay_tuesday=true`
 * `pay_tuesday`
 
-The following also have the same result, however note that because the value has more than one token, quotes must be used:
+If the values consist of more than one token, quotes must be used.
+The following examples both yield the same result:
 
 * `pay_tuesday="maybe not"`
 * `pay_tuesday='maybe not'`
 
-#### Remaining Markup
+### Remaining Markup
 
 After your plugin has parsed all the keyword options and name/value parameters,
 call `@helper.remaining_markup` to obtain the remaining markup that was passed to your plugin.
 
 
-### `no_arg_parsing` Optimization
+## Liquid Variable Definitions
+
+`jekyll_plugin_support` provides support for
+[Liquid variables](https://shopify.github.io/liquid/tags/variable/)
+to be defined in `_config.yml`, in a section called `liquid-vars`.
+The following `_config.yml` fragment defines 3 variables called `var1`, `var2` and `var3`:
+
+```yaml
+liquid-vars:
+  var1: value1
+  var2: 'value 2'
+  var3: value3
+```
+
+Liquid variables defined in this manner are intended to be embedded in a webpage.
+They are expanded transparently, and can be referenced like any other Liquid variable.
+These Liquid variables can be passed as parameters to other plugins and includes.
+
+In the following example web page, the Liquid variable called `var1` is expanded as part of the displayed page.
+Liquid variables `var1` and `var2` are expanded and passed to the `my_plugin` plugin.
+
+```html
+This is the value of <code>var1</code>: {{var1}}.
+
+{% my_plugin param1="{{var1}}" param2="{{var2}}" %}
+```
+
+`Jekyll_plugin_support` expands all but one of the
+[plugin variables described above](#predefined-variables),
+replacing Liquid variable references with their values.
+The exception is `@argument_string`, which is not expanded.
+
+
+### Liquid Variable Values Specific To Production And Development Modes
+
+`jekyll_plugin_support` allows Liquid variables defined in `_config.yml` to have different values
+when Jekyll is running in `development`, `production` and `test` modes.
+When injecting variables into your Jekyll website, `Jekyll_plugin_support`
+refers to definitions specific to the current environment,
+and then refers to other definitions that are not overridden.
+
+Here is an example:
+
+```yaml
+liquid-vars:
+  development:
+    var1: 'http://localhost:4444/demo_block_tag.html'
+    var2: 'http://localhost:4444/demo_inline_tag.html'
+  production:
+    var1: 'https://github.com/django/django/blob/3.1.7'
+    var2: 'https://github.com/django-oscar/django-oscar/blob/3.0.2'
+  var3: 'https://github.com/mslinn'
+```
+
+For the above, the following variable values are set in `development` mode:
+
+* `var1`: `http://localhost:4444/demo_block_tag.html`
+* `var2`: `http://localhost:4444/demo_inline_tag.html`
+* `var3`: `https://github.com/mslinn`
+
+... and the following variable values are set in `production` and `test` modes:
+
+* `var1`: `https://github.com/django/django/blob/3.1.7`
+* `var2`: `https://github.com/django-oscar/django-oscar/blob/3.0.2`
+* `var3`: `https://github.com/mslinn`
+
+
+### Liquid Variables in `jekyll_plugin_support` Subclasses
+
+You can define additional Liquid variables in plugins built using `jekyll_plugin_support`.
+To do this, make entries in `_config.yml` under a key named after the value of `@tag_name`.
+
+For example, let&rsquo;s imagine you create a plugin using `jekyll_plugin_support`,
+and hou register it with the name `phonetic_alphabet`.
+You could define Liquid variables that would be made available to content pages in web applications that
+incorporate the `phonetic_alphabet` plugin.
+The following section in `_config.yml` defines variables called `x`, `y` and `z`,
+with values `xray`, `yankee` and `zulu`, respectively:
+
+```yaml
+phonetic_alphabet:
+  x: xray
+  y: yankee
+  z: zulu
+```
+
+The above definitions allow you to write content pages that use those variables, like the following page containing markup:
+
+```html
+---
+layout: default
+title: Variable demo
+---
+The letter `x` is pronounced {{x}}.
+Similarly, the letters `y` and `z` are pronounced {{y}} and {{z}}.
+```
+
+
+## `no_arg_parsing` Optimization
 
 If your tag or block plugin only needs access to the raw arguments passed from the web page,
 without tokenization, and you expect that the plugin might be invoked with large amounts of text,
@@ -213,8 +349,10 @@ derive your plugin from `JekyllBlockNoArgParsing` or `JekyllTagNoArgParsing`.
 
 ## Subclass Attribution
 
-`JekyllTag` and `JekyllBlock` subclasses of `jekyll_plugin_support` can utilize the `attribution` option IFF they are published as a gem.
+`JekyllTag` and `JekyllBlock` subclasses of `jekyll_plugin_support` can utilize the `attribution`
+option if they are published as a gem.
 `JekyllTagNoArgParsing` and `JekyllBlockNoArgParsing` subclasses cannot.
+This feature is usually only desired for `JekyllBlock` subclasses.
 
 * When used as a keyword option, a default value is used for the attribution string.
 * When used as a name/value option, the attribution string can be specified.
@@ -237,10 +375,12 @@ The `id` attribute is in the sample HTML above is randomized so more than one at
 Typical usage for the `attribution` tag is:
 
 ```html
-{% my_tag attribution %}
+{% my_block_tag attribution %}
+  Content of my_block_tag.
+{% endmy_block_tag %}
 ```
 
-Normal processing of `my_tag` is augmented by interpolating the attribution format string,
+Normal processing of `my_block_tag` is augmented by interpolating the attribution format string,
 which is a Ruby-compatible interpolated string.
 
 The default attribution format string is:
@@ -275,17 +415,11 @@ HEREDOC
 ```
 
 
-## Additional Information
-
-More information is available on
-[Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html).
-
-
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies.
+After checking out the `jekyll_plugin_suppprt` repository, run `bin/setup` to install dependencies.
 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+`bin/console` provides an interactive prompt that allows you to experiment.
 
 
 To build and install this gem onto your local machine, run:
@@ -314,11 +448,25 @@ jekyll_plugin_support (0.1.0)
 ```
 
 
-## Demo
+### Pry Breakpoint On StandardError
+
+A `pry` breakpoint will be set in the `StandardError` handler if `pry_on_standard_error: true`
+is set in variable configuration section of `_config.yml`.
+
+For example, if your plugin is called `blah`, enable the breakpoint with the following section:
+
+```yml
+blah:
+  pry_on_standard_error: true
+```
+
+
+## Demonstration Plugins and Website
 
 A demo / test website is provided in the `demo` directory.
 It can be used to debug the plugin or to run freely.
 
+
 ### Run Freely
 
  1. Run from the command line:
@@ -327,31 +475,57 @@ It can be used to debug the plugin or to run freely.
     $ demo/_bin/debug -r
     ```
 
- 2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+ 2. View the generated website,
+    which might be at [`http://localhost:4444`](http://localhost:4444),
+    depending on how you configured it.
+
 
 ### Plugin Debugging
 
  1. Set breakpoints in Visual Studio Code.
 
- 2. Initiate a debug session from the command line:
+ 2. Initiate a debug session from the command line by running the `demo/_bin/debug` script:
 
     ```shell
     $ demo/_bin/debug
+    Fetching gem metadata from https://rubygems.org/..........
+    Resolving dependencies...
+    Fetching public_suffix 5.0.4
+    Fetching nokogiri 1.15.5 (x86_64-linux)
+    Installing public_suffix 5.0.4
+    Installing nokogiri 1.15.5 (x86_64-linux)
+    Bundle complete! 17 Gemfile dependencies, 96 gems now installed.
+    Use `bundle info [gemname]` to see where a bundled gem is installed.
+
+    INFO PluginMetaLogger: Loaded DraftFilter plugin.
+    INFO PluginMetaLogger: Loaded outline_js v1.2.1 plugin.
+    INFO PluginMetaLogger: Loaded outline v1.2.1 plugin.
+    Configuration file: /mnt/f/jekyll_plugin_support/demo/_config.yml
+              Cleaner: Removing /mnt/f/jekyll_plugin_support/demo/_site...
+              Cleaner: Removing /mnt/f/jekyll_plugin_support/demo/.jekyll-metadata...
+              Cleaner: Removing /mnt/f/jekyll_plugin_support/demo/.jekyll-cache...
+              Cleaner: Nothing to do for .sass-cache.
+    DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:37177)
+    DEBUGGER: wait for debugger connection...
     ```
 
- 3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch
-     configuration called `Attach with rdbg`.
+ 3. Once the `DEBUGGER: wait for debugger connection...` message appears,
+    run the Visual Studio Code launch configuration called `Attach with rdbg`.
 
- 4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+ 4. View the generated website,
+    which might be at [`http://localhost:4444`](http://localhost:4444),
+    depending on how you configured it.
 
 
 ### Build and Push to RubyGems
 
-To release a new version,
+To release a new version:
 
   1. Update the version number in `version.rb`.
-  2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
-  3. Run the following:
+  2. Add an entry to `CHANGELOG.md` describing the changes since the previous version.
+  3. Commit all changes to git;
+     if you don't the next step might fail with an unexplainable error message.
+  4. Run the following:
 
      ```shell
      $ bundle exec rake release

data/jekyll_plugin_support.gemspec

@@ -1,6 +1,6 @@
 require_relative 'lib/jekyll_plugin_support/version'
 
-Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
+Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_plugin_support'
 
   spec.bindir = 'exe'
@@ -24,7 +24,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   END_MESSAGE
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
-  spec.summary = 'Provides support for writing Jekyll plugins.'
+  spec.summary = 'Provides a framework for writing and testing Jekyll plugins'
   spec.test_files = spec.files.grep %r{^(test|spec|features)/}
   spec.version = JekyllPluginSupportVersion::VERSION
 
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.add_dependency 'jekyll', '>= 3.5.0'
   spec.add_dependency 'jekyll_plugin_logger'
   spec.add_dependency 'key-value-parser'
+  spec.add_dependency 'pry'
 end

data/lib/jekyll_custom_error.rb

@@ -0,0 +1,55 @@
+require 'facets/string/camelcase'
+require 'facets/string/snakecase'
+
+module Jekyll
+  # Use like this:
+  # CustomError.new(:MyError, 'blah', 'asdf')
+  class CustomError < StandardError
+    def self.factory(name)
+      return if Object.const_defined? name
+
+      puts "Defining #{name}".yellow
+      eval "#{name} = Class.new Jekyll::CustomError" # rubocop:disable Style/EvalWithLocation, Security/Eval
+    end
+
+    def error_name
+      self.class.name.split('::').last
+    end
+
+    def calling_file
+      file_fq, _line_number, _extra = backtrace[0].split(':')
+      file_fq
+    end
+
+    # @return HTML <div> tag with class set to the snake_case version of the error class name.
+    def html_message
+      shorten_backtrace
+      line_number = self.class.class_variable_get :@@line_number
+      path = self.class.class_variable_get :@@path
+      <<~END_MSG
+        <div class='#{error_name.snakecase}'>
+          #{self.class} raised in #{calling_file} while processing line #{line_number} (after front matter) of #{path}
+          #{message}
+        </div>
+      END_MSG
+    end
+
+    def logger_message
+      shorten_backtrace
+      kaller = caller(1..1).first
+      line_number = self.class.class_variable_get :@@line_number
+      path = self.class.class_variable_get :@@path
+      <<~END_MSG
+        #{error_name} raised in #{kaller} while processing line #{line_number} (after front matter) of #{path}
+          #{message}
+      END_MSG
+    end
+
+    def shorten_backtrace(backtrace_element_count = 3)
+      b = backtrace[0..backtrace_element_count - 1].map do |x|
+        x.gsub(Dir.pwd + '/', './')
+      end
+      set_backtrace b
+    end
+  end
+end