jekyll_plugin_support 1.0.3 → 3.0.0

data/README.md

@@ -1,22 +1,26 @@
 # `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 provides a framework for writing and testing Jekyll plugins.
+After writing over two dozen Jekyll plugins, I distilled the common code into `Jekyll_plugin_support`.
+This F/OSS Ruby gem facilitates writing and testing Jekyll plugins and handles the standard housekeeping that every Jekyll
+inline and block tag plugin requires.
+Logging, parsing arguments, obtaining references to site and page objects, etc. are all handled.
+The result is faster Jekyll plugin writing with fewer bugs.
 
 `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:
+Public plugins that use `jekyll_plugin_support` include:
 
 <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_draft'><code>jekyll_draft</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_google_translate'><code>jekyll_google_translate</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>
@@ -33,55 +37,87 @@ Jekyll plugin tags created from `jekyll_plugin_support` framework automatically
 1. Boilerplate is removed, so you can focus on the required logic and output.
 2. Arguments are parsed for keywords and name/value parameters.
 3. Single or double quotes can be used for arguments and parameters.
-4. Important variables are defined.
+4. Important variables are predefined.
 5. Error handling is standardized, and includes an automatically defined error type
    and corresponding CSS tag for each Jekyll tag.
-6. Liquid variables can be passed as parameters to tags, and used in the body of block tags.
-7. Registration is automatic, and important configuration details are reported during registration.
+6. Jekyll and Liquid variables, including `layout`, `page` and `include` variables,
+   can be passed as parameters to tags, and used in the body of block tags.
+7. Plugin registration is integrated, and important configuration details are reported during registration.
 8. A custom logger is created for each tag, independent of the default Jekyll logger.
 9. Variables can be defined in `_config.yml`, and optionally have different values for debug mode,
    production mode and test mode.
 10. An attribution message is available.
 11. Draft pages are automatically detected.
+12. A demonstration website is provided for easy testing of every plugin.
+13. Visual Studio Code debugging is set up for the plugin code and the demo website.
+14. Plugins can be subclassed.
+15. [`Nugem`](https://mslinn.com/ruby/6800-nugem.html) can create working scaffolding for new plugins built
+    using `jekyll_plugin_support`.
+16. Four new attributes are added to
+  [`site`](https://jekyllrb.com/docs/variables/#site-variables):
 
-In addition, a demonstration website is provided for easy testing of your plugins.
+    a. `all_collections` includes all documents in all collections.
 
+    b. `all_documents` includes `all_collections` plus all standalone pages.
+
+    c. `everything` includes `all_documents` plus all static files.
+
+    d. `sorted_lru_files` is used by a new binary search lookup for matching page suffixes.
+      The `jekyll_href` and `jekyll_draft` plugins use this feature.
 
 ## Installation
 
+### For A Jekyll Website
+
 `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,
+If you want to write a custom Jekyll 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', '>= 0.8.0'
+  gem 'jekyll_plugin_support', '>= 1.1.0'
   # ...
 end
 ```
 
-Otherwise, if your custom plugin will be packaged into a gem, add the following to your plugin’s `.gemspec`:
+Run the standard `jekyll_plugin_support` setup procedure:
+
+```shell
+$ bin/setup
+```
+
+
+### As a Gem Dependency
+
+If your custom plugin will be packaged into a gem, add the following to your plugin’s `.gemspec`:
 
 ```ruby
 Gem::Specification.new do |spec|
   # ...
-  spec.add_dependency 'jekyll_plugin_support', '>= 0.8.0'
+  spec.add_dependency 'jekyll_plugin_support', '>= 1.1.0'
   # ...
 end
 ```
 
-Install the `jekyll_plugin_support` Ruby gem and mark it as a dependency of your project by typing:
+Install the `jekyll_plugin_support` gem into your plugin project in the usual manner:
+
+```shell
+$ bundle
+```
+
+Copy the CSS classes from
+[`demo/assets/css/jekyll_plugin_support.css`](demo/assets/css/jekyll_plugin_support.css)
+to your Jekyll project&rsquo;s CSS file.
 
-  ```shell
-  $ bundle
-  ```
 
-Copy the CSS classes from `demo/assets/css/jekyll_plugin_support.css` to your Jekyll project&rsquo;s CSS file.
 
 
 ## About `jekyll_plugin_support`
 
+This Jekyll plugin includes a generator,
+triggered by a high-priority hook, and a block tag called `all_collections`.
+
 `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.
@@ -104,13 +140,21 @@ 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
+Your implementation of render_impl can parse parameters passed to your tag, as described in
 [Tag Parameter Parsing](http://mslinn.com/jekyll/10100-jekyll-plugin-background.html#params).
 
+In addition, within <code>render_impl</code>,
+the arguments passed to the tag will have been tokenized and parsed,
+with Jekyll and Liquid variables substituted for their values,
+and all the public Jekyll variables will be available as instance variables.
+Error handling will also have been set up,
+and access to your tag's entry within <code>_config.yml</code> will have been set up.
+
+
 
 ## General Usage
 
-Please see the [`demo/`](demo/) project for a well-documented set of demonstration Jekyll plugins that are built from `jekyll_plugin_support`.
+Please see the [`demo/`](demo/) project for a well-documented set of demonstration Jekyll plugins 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.
 
@@ -141,7 +185,196 @@ because both `JekyllSupport` classes define this method.
 
 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 any text enclosed within your block.
+For block tags, a single parameter is required, which receives any text enclosed within your block by the website author.
+
+
+### New `Site` Attributes
+
+No explicit initialization or setup is required.
+Jekyll plugins can access the value of
+`site.all_collections`, `site.all_documents` and `site.everything`;
+however, Liquid code in Jekyll pages and documents cannot.
+
+
+### Excluding Files
+
+There are two ways to exclude files from the new `site` attributes.
+
+1) The [`exclude` entry in `_config.yml`](https://jekyllrb.com/docs/configuration/options#global-configuration)
+   can be used as it normally would.
+
+2) Adding the following entry to a page&rsquo;s front matter causes that page to be excluded
+  from the collection created by this plugin:
+
+   ```html
+   ---
+   exclude_from_all: true
+   ---
+   ```
+
+### `all_collections` Plugin Usage
+
+Jekyll generators and tags receive an enhanced version of the `site` Jekyll variable.
+
+
+#### From a Custom Plugin
+
+In the following example of how to use the `all_collections` plugin in a custom plugin,
+the `do_something_with` function processes all `Jekyll::Page`s, `Jekyll:Document`s, and static files.
+
+```ruby
+@site.everything.each do |apage|
+  do_something_with apage
+end
+```
+
+
+#### Using the Block Tag
+
+The general form of the Jekyll tag, including all options, is:
+
+```html
+{% all_collections
+  date_column='date|last_modified'
+  heading='All Posts'
+  id='asdf'
+  sort_by='SORT_KEYS'
+%}
+```
+
+
+##### `date_column` Attribute
+
+One of two date columns can be displayed in the generated HTML:
+either `date` (when the article was originally written),
+or `last_modified`.
+The default value for the `date_column` attribute is `date`.
+
+
+##### `heading` Attribute
+
+If no `heading` attribute is specified, a heading will automatically be generated, which contains the `sort_by` values,
+for example:
+
+```html
+{% all_collections id='abcdef' sort_by="last_modified" %}
+```
+
+The above generates a heading like:
+
+```html
+<h2 id="abcdef">All Posts Sorted By last_modified</h2>
+```
+
+To suppress both a `h2` heading (and the enclosed `id`) from being generated,
+specify an empty string for the value of `heading`:
+
+```html
+{% all_collections heading='' %}
+```
+
+
+##### `id` Attribute
+
+If your Jekyll layout employs [`jekyll-toc`](https://github.com/allejo/jekyll-toc), then `id` attributes are important.
+The `jekyll-toc` include checks for `id` attributes in `h2` ... `h6` tags, and if found,
+and if the attribute value is enclosed in double quotes
+(`id="my_id"`, not single quotes like `id='my_id'`),
+then the heading is included in the table of contents.
+
+To suppress an `id` from being generated,
+and thereby preventing the heading from appearing in the automatically generated table of contents from `jekyll-toc`,
+specify an empty string for the value of `id`, like this:
+
+```html
+{% all_collections id='' %}
+```
+
+
+##### `SORT_KEYS` Values
+
+`SORT_KEYS` specifies how to sort the collection.
+Values can include one or more of the following attributes:
+`date`, `destination`, `draft`, `label`, `last_modified`, `last_modified_at`, `path`, `relative_path`,
+`title`, `type`, and `url`.
+Ascending sorts are the default; however, a descending sort can be achieved by prepending `-` before an attribute.
+
+To specify more than one sort key, provide a comma-delimited string of values.
+Included spaces are ignored.
+For example, specify the primary sort key as `draft`,
+the secondary sort key as `last_modified`,
+and the tertiary key as `label`:
+
+```html
+{% all_collections
+  date_column='last_modified'
+  heading='All Posts'
+  id='asdf'
+  sort_by='draft, last_modified, label'
+%}
+```
+
+
+#### Liquid Usage Examples
+
+Here is a short Jekyll page, including front matter,
+demonstrating this plugin being invoked with all default attribute values:
+
+```html
+---
+description: "
+  Dump of all collections, sorted by date originally written, newest to oldest.
+  The heading text will be <code>All Posts Sorted By -date</code>
+"
+layout: default
+title: Testing, 1, 2, 3
+---
+{% all_collections %}
+```
+
+Following are examples of how to specify the sort parameters.
+
+**Explicitly express the default sort**<br>
+(sort by the date originally written, newest to oldest):
+
+```html
+{% all_collections sort_by="-date" %}
+```
+
+Sort by date, from oldest to newest:
+
+```html
+{% all_collections sort_by="date" %}
+```
+
+**Sort by the date last modified, oldest to newest:**
+
+```html
+{% all_collections sort_by="last_modified" %}
+```
+
+**Sort by the date last modified, newest to oldest:**
+
+```html
+{% all_collections sort_by="-last_modified" %}
+```
+
+**Several attributes can be specified as sort criteria**<br>
+by passing them as a comma-delimited string.
+Included spaces are ignored:
+
+```html
+{% all_collections sort_by="-last_modified, -date" %}
+{% all_collections sort_by="-last_modified, title" %}
+{% all_collections sort_by="-last_modified, -date, title" %}
+```
+
+**The following two examples produce the same output:**
+
+```html
+{% all_collections sort_by="-last_modified,-date" %}
+{% all_collections sort_by="-last_modified, -date" %}
+```
 
 
 ## Predefined Plugin Variables
@@ -150,10 +383,12 @@ For block tags, a single parameter is required, which contains any text enclosed
 
 * `@argument_string` Unparsed markup passed as a parameter to your block tag and inline tag.
 
+* `@argv` returns any remaining tokens after `parameter_specified?` has been invoked.
+
 * [`@attribution`](#subclass-attribution) Attribution markup
 
 * [`@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
+  The [YAML](https://yaml.org/) Jekyll site configuration file
 
 * [`@helper`](https://github.com/mslinn/jekyll_plugin_support/blob/master/lib/jekyll_plugin_helper.rb)
   `JekyllPluginHelper` instance for your plugin.
@@ -165,7 +400,7 @@ For block tags, a single parameter is required, which contains any text enclosed
 * [`@mode`](https://jekyllrb.com/docs/configuration/environments/)
   Indicates `production`, `test` or `development` mode.
 
-* [`@page`](https://jekyllrb.com/docs/variables/#page-variables) Page variables
+* [`@page`](https://jekyllrb.com/docs/variables/#page-variables) `Jekyll::Page` variables
 
 * [`@paginator`](https://jekyllrb.com/docs/variables/#page-variables) Pagination variables
 
@@ -322,7 +557,7 @@ call `@helper.remaining_markup` to obtain the remaining markup that was passed t
 
 `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`.
+to be defined in `_config.yml`, in a section called `liquid_vars`.
 These variables behave exactly like Liquid variables defined by `assign` and `capture` expressions,
 except they are global in scope; these variables are available in every Jekyll web page.
 
@@ -339,7 +574,7 @@ Liquid variables defined in this manner are intended to be embedded in a webpage
 They are can be used like any other Liquid variable.
 
 
-### Variable Expansion
+## Variable Expansion
 
 Jekyll expands Liquid variable references during the page rendering process.
 Jekyll does not expand Liquid variable references passes as parameters to tag and block plugins, however.
@@ -444,7 +679,27 @@ Similarly, the letters `y` and `z` are pronounced {{y}} and {{z}}.
 ```
 
 
-### Automatically Created Error Classes
+### Evaluating Include Variables
+
+This information is only useful if a plugin might be executed from within an included file.
+
+While Liquid handles regular variables, Jekyll has special handling for variables defined by include parameters.
+For example, the following defines a variable in the `include` scope called `var1`
+when processing the body of an included file:
+
+```html
+{% include myfile.html var1='value1' %}
+```
+
+You can obtain the value of this variable from the `render_impl` method of a
+`JekyllSupport::JekyllTag` or `JekyllSupport::JekyllBlock` subclass as follows:
+
+```ruby
+  @var1 = @scopes.first['include']&.[]('var1')
+```
+
+
+## Automatically Created Error Classes
 
 `JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag` subclasses
 automatically create error classes, named after the subclass.
@@ -452,7 +707,8 @@ automatically create error classes, named after the subclass.
 For example, if you create a `JekyllSupport::JekyllBlock` subclass called `DemoBlockTag`,
 the automatically generated error class will be called `DemoBlockTagError`.
 
-Although you could use it as you would any other error class, `JekyllPluginSupport` provides some helper methods.
+Although you could use it as you would any other error class, `JekyllPluginSupport`
+provides additional helper methods.
 These methods fill in the page path and line number that caused the error, shorten the stack trace,
 log an error message, and can be used to return an HTML-friendly version of the message to the web page.
 
@@ -482,7 +738,7 @@ Error class methods have been provided for standardized and convenient error han
 * `html_message` - The same as `logger_message`, but constructed with HTML.
 
 
-### Self-Reporting Upon Registration
+## Self-Reporting Upon Registration
 
 When each tag is registered, it self-reports, for example:
 
@@ -514,6 +770,83 @@ If your tag or block plugin only needs access to the raw arguments passed from t
 without tokenization, and you expect that the plugin might be invoked with large amounts of text,
 derive your plugin from `JekyllBlockNoArgParsing` or `JekyllTagNoArgParsing`.
 
+## Writing Plugins
+
+The following minimal examples define `VERSION`,
+which is important because `JekyllPluginHelper.register` logs that value when registering the plugin.
+
+This is how you would define plugins in the `_plugins` directory
+
+**Boilerplate for an inline tag plugin**
+
+```ruby
+require 'jekyll_plugin_support'
+
+module Jekyll
+  class DemoTag < JekyllSupport::JekyllTag
+    VERSION = '0.1.0'.freeze
+
+    def render_impl
+      @helper.gem_file __FILE__ # Enables attribution; only works when plugin is a gem
+      # Your Jekyll plugin logic goes here
+    end
+
+    JekyllPluginHelper.register(self, 'demo_tag')
+  end
+end
+```
+
+**Boilerplate for a tag block plugin**
+
+```ruby
+require 'jekyll_plugin_support'
+
+module Jekyll
+  class DemoBlock < JekyllSupport::JekyllBlock
+    VERSION = '0.1.0'.freeze
+
+    def render_impl(text)
+      @helper.gem_file __FILE__ # Enables attribution; only works when plugin is a gem
+      # Your Jekyll plugin logic goes here
+    end
+
+    JekyllPluginHelper.register(self, 'demo_block')
+  end
+end
+```
+
+If your plugin is packaged as a gem, then you might need to include `version.rb` into the plugin class.
+For example, if your version module looks like this:
+
+**lib/my_plugin/version.rb**:
+
+```ruby
+module MyPluginVersion
+  VERSION = '0.5.0'.freeze
+end
+```
+
+Then your plugin can incorporate the VERSION constant into your plugin like this:
+
+**lib/my_plugin.rb**:
+
+```ruby
+require 'jekyll_plugin_support'
+require_relative 'my_plugin/version'
+
+module Jekyll
+  class MyBlock < JekyllSupport::JekyllBlock
+    include MyPluginVersion
+
+    def render_impl(text)
+      @helper.gem_file __FILE__ # Enables attribution; only works when plugin is a gem
+      # Your code here
+    end
+
+    JekyllPluginHelper.register(self, 'demo_block')
+  end
+end
+```
 
 ## Attribution
 
@@ -583,7 +916,7 @@ An alternative attribution string can be specified properties can be output usin
 {% my_tag attribution="Generated by the #{name} #{version} Jekyll plugin, written by #{author} #{date}" %}
 ```
 
-## Subclassing
+## Subclassing Plugins
 
 Jekyll plugins created using `jekyll_plugin_support` are implemented as Ruby classes.
 If you would like to create a version of an existing Jekyll plugin, you will need to subclass the plugin.
@@ -599,6 +932,133 @@ redef_without_warning :VERSION, '0.1.0'.freeze
 ```
 
 
+## Generator
+
+This plugin incorporates a generator, which adds four new attributes to
+[`site`](https://jekyllrb.com/docs/variables/#site-variables):
+`all_collections`, `all_documents`, `everything`, and `sorted_lru_files`.
+
+These three attributes can be referenced as `site.everything`, `site.all_collections`
+and `site.all_documents`.
+
+* `all_collections` includes all documents in all collections.
+
+* `all_documents` includes `all_collections` plus all standalone pages.
+
+* `everything` includes `all_documents` plus all static files.
+
+* `sorted_lru_files` is used by a new binary search lookup for matching page suffixes.
+  Currently only `jekyll_href` and `jekyll_draft` use this feature.
+
+
+### Collection Management
+
+Jekyll provides inconsistent attributes for
+[`site.pages`](https://jekyllrb.com/docs/pages/),
+[`site.posts`](https://jekyllrb.com/docs/posts/) and
+[`site.static_files`](https://jekyllrb.com/docs/static-files/).
+
+
+* While the `url` attributes of items in `site.posts` and `site.pages` start with a slash (/),
+  `site.static_files` items do not have a `url` attribute.
+* Static files have a `relative_path` attribute, which starts with a slash (/),
+  but although that attribute is also provided in `site.posts` and `site.pages`,
+  those values do not start with a slash.
+* Paths ending with a slash (`/`) imply that a file called `index.html` should be fetched.
+* HTML redirect files created by the
+  [`jekyll-redirect-from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin,
+  which are included in `site.static_files`, should be ignored.
+
+These inconsistencies mean that combining the standard three collections of files
+provided as `site` attributes will create a new collection that is difficult
+to process consistently:
+
+```ruby
+# This pseudocode creates `oops`, which is problematic to process consistently
+oops = site.all_collections + site.pages + site.static_files
+```
+
+`oops`, above, is difficult to process because of inconsistencies in the provided attributes
+and how the attributes are constructed.
+
+
+### Solving The Problem
+
+The generator normalizes these inconsistencies by utilizing the `APage` class
+and filtering out HTML redirect files.
+
+The `all_collections` collection contains `APage` representations of `site.collections`.
+
+The `all_documents` collection contains `APage` representations of `site.pages`.
+
+The `everything` collection contains `APage` representations of:
+
+```text
+# Pseudocode
+site.collections + site.pages + site.static_files - HTML_redirect_files
+```
+
+
+## The `APage` Class
+
+The `site.all_collections`, `site.all_documents` and `site.everything` attributes
+consist of arrays of [`APage`](lib/hooks/a_page.rb) instances.
+
+The `APage` class has the following attributes:
+`content` (HTML or Markdown), `data` (array), `date` (Ruby Date), `description`, `destination`,
+`draft` (Boolean), `ext`, `href`, `label`, `last_modified` or `last_modified_at` (Ruby Date),
+`layout`, `origin`, `path`, `relative_path`, `tags`, `title`, `type`, and `url`.
+
+* `href` always starts with a slash.
+  This value is consistent with `a href` values in website HTML.
+  Paths ending with a slash (`/`) have `index.html` appended so the path specifies an actual file.
+
+* `origin` indicates the original source of the item.
+  Possible values are `collection`, `individual_page` and `static_file`.
+  Knowing the origin of each item allows code to process each type of item appropriately.
+
+
+## `all_collections` Block Tag
+
+The `all_collections` block tag creates a formatted listing of Jekyll files.
+The ordering is configurable; by default, the listing is sorted by `date`, newest to oldest.
+The `all_collections` tag has a `data_source` parameter that specifies which new property to report on
+(`all_collections`, `all_documents`, or `everything`).
+
+
+## Requirements
+
+All the pages in the Jekyll website must have an implicit date
+(for example, all posts are assigned this property by Jekyll),
+or an explicit `date` set in front matter, like this:
+
+```html
+---
+date: 2022-01-01
+---
+```
+
+If a front matter variable called `last_modified` or `last_modified_at` exists,
+its value will be converted to a Ruby `Date`:
+
+```html
+---
+last_modified: 2023-01-01
+---
+```
+
+Or:
+
+```html
+---
+last_modified_at: 2023-01-01
+---
+```
+
+Otherwise, if `last_modified` or `last_modified_at` is not present in the front matter for a page,
+the `date` value will be used last modified date value.
+
+
 ## Development
 
 After checking out the `jekyll_plugin_suppprt` repository, run `bin/setup` to install dependencies.
@@ -632,6 +1092,51 @@ jekyll_plugin_support (0.1.0)
 ```
 
 
+### Build and Install Locally
+
+To build and install this gem onto your local machine, run:
+
+```shell
+$ bundle exec rake install
+jekyll_all_collections 0.3.8 built to pkg/jekyll_all_collections-0.3.8.gem.
+jekyll_all_collections (0.3.8) installed.
+```
+
+Examine the newly built gem:
+
+```shell
+$ gem info jekyll_all_collections
+
+*** LOCAL GEMS ***
+
+jekyll_all_collections (0.3.8)
+    Author: Mike Slinn
+    Homepage:
+    https://www.mslinn.com/jekyll_plugins/jekyll_all_collections.html
+    License: MIT
+    Installed at (0.3.8): /home/mslinn/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0
+
+    Provides normalized collections and extra functionality for Jekyll websites.
+```
+
+
+### Build and Push to RubyGems
+
+To release a new version:
+
+1. Update the version number in `version.rb`.
+2. Add an entry in `CHANGELOG.md` describing the changes since the last release.
+3. Commit all changes to git; if you don't the next step might fail with a confusing error message.
+4. Run the following:
+
+    ```shell
+    $ bundle exec rake release
+    ```
+
+    The above creates a git tag for the version, commits the created tag,
+    and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
+
+
 ### Pry Breakpoint On StandardError
 
 A `pry` breakpoint will be set in the `StandardError` handler if `pry_on_standard_error: true`
@@ -645,11 +1150,259 @@ blah:
 ```
 
 
+## Debugging
+
+You can control the verbosity of log output by adding the following to `_config.yml` in your Jekyll project:
+
+```yaml
+plugin_loggers:
+  AllCollectionsTag::AllCollectionsTag: warn
+```
+
+1. First set breakpoints in the Ruby code that interests you.
+
+2. You have several options for initiating a debug session:
+
+   1. Use the **Debug Demo** Visual Studio Code launch configuration.
+
+   2. Type the `demo/_bin/debug` command, without the `-r` options shown above.
+
+      ```console
+      ... lots of output as bundle update runs...
+      Bundle updated!
+
+      INFO PluginMetaLogger: Loaded AllCollectionsHooks v0.2.0 :site, :pre_render, :normal hook plugin.
+      INFO PluginMetaLogger: Loaded DraftFilter plugin.
+      INFO PluginMetaLogger: Loaded all_collections v0.2.0 tag plugin.
+      Configuration file: /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/_config.yml
+                Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/_site...
+                Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/.jekyll-metadata...
+                Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/.jekyll-cache...
+                Cleaner: Nothing to do for .sass-cache.
+      Fast Debugger (ruby-debug-ide 0.7.3, debase 0.2.5.beta2, file filtering is supported) listens on 0.0.0.0:1234
+      ```
+
+   3. Run `bin/attach` and pass the directory name of a Jekyll website that has a suitable script called `_bin/debug`.
+      The `demo` subdirectory fits this description.
+
+      ```console
+      $ bin/attach demo
+      Successfully uninstalled jekyll_all_collections-0.1.2
+      jekyll_all_collections 0.1.2 built to pkg/jekyll_all_collections-0.1.2.gem.
+      jekyll_all_collections (0.1.2) installed.
+      Fast Debugger (ruby-debug-ide 0.7.3, debase 0.2.4.1, file filtering is supported) listens on 0.0.0.0:1234
+      ```
+
+
+3. Attach to the debugger process if required.
+  This git repo includes two [Visual Studio Code launch configurations](./.vscode/launch.json) for this purpose labeled
+  **Attach rdbg** and **Attach with ruby_lsp**.
+
+4. Point your web browser to http://localhost:4444
+
+If a debugging session terminates abruptly and leaves ports tied up,
+run the `demo/_bin/release_port` script.
+
+
 ## Demonstration Plugins and Website
 
-A demo / test website is provided in the `demo` directory.
+A demo / test website is provided in the [`demo`](demo) directory.
 It can be used to debug the plugin or to run freely.
 
+### Examining the Demo Plugins
+
+The following example plugins use
+[Ruby’s squiggly heredoc operator](https://ruby-doc.org/core-2.5.0/doc/syntax/literals_rdoc.html#label-Here+Documents) (`<<~`).
+The squiggly heredoc operator removes the outermost indentation.
+This provides easy-to-read multiline text literals.
+
+**demo/_plugins/demo_tag.rb**:
+
+```ruby
+require 'jekyll_plugin_support'
+
+# Use the JekyllSupport module namespace so the self methods are automajically found
+module JekyllSupport
+  DemoInlineTagError = JekyllSupport.define_error
+
+  class DemoTag < JekyllTag
+    VERSION = '0.1.2'.freeze
+    # JekyllSupport.redef_without_warning 'VERSION', '0.1.2'.freeze
+
+    def render_impl
+      @demo_tag_error = @helper.parameter_specified? 'raise_demo_tag_error'
+      @keyword1       = @helper.parameter_specified? 'keyword1'
+      @keyword2       = @helper.parameter_specified? 'keyword2'
+      @name1          = @helper.parameter_specified? 'name1'
+      @name2          = @helper.parameter_specified? 'name2'
+      @standard_error = @helper.parameter_specified? 'raise_standard_error'
+
+      if @tag_config
+        @die_on_demo_tag_error = @tag_config['die_on_demo_tag_error'] == true
+        @die_on_standard_error = @tag_config['die_on_standard_error'] == true
+      end
+
+      raise DemoInlineTagError, 'This DemoInlineTagError error is expected.' if @demo_tag_error
+      raise StandardError, 'This StandardError error is expected.' if @standard_error
+
+      # _infinity = 1 / 0 if @standard_error # Not required
+
+      output
+    rescue DemoInlineTagError => e # jekyll_plugin_support handles StandardError
+      @logger.error { e.logger_message }
+      exit! 1 if @die_on_demo_tag_error
+
+      e.html_message
+    end
+
+    private
+
+    def output
+      <<~END_OUTPUT
+        <pre># jekyll_plugin_support becomes able to perform variable substitution after this variable is defined.
+        # The value could be updated at a later stage, but no need to add that complexity unless there is a use case.
+        @argument_string="#{@argument_string}"
+
+        @helper.argv=
+          #{@helper.argv&.join("\n  ")}
+
+        # Liquid variable name/value pairs
+        @helper.params=
+          #{@helper.params&.map { |k, v| "#{k}=#{v}" }&.join("\n  ")}
+
+        # The keys_values property serves no purpose any more, consider it deprecated
+        @helper.keys_values=
+          #{(@helper.keys_values&.map { |k, v| "#{k}=#{v}" })&.join("\n  ")}
+
+        @layout='#{@layout}'
+        @page.keys='#{@page.keys}'
+
+        remaining_markup='#{@helper.remaining_markup}'
+
+        @keyword1='#{@keyword1}'
+        @keyword2='#{@keyword2}'
+        @name1='#{@name1}'
+        @name2='#{@name2}'</pre>
+      END_OUTPUT
+    end
+
+    JekyllPluginHelper.register(self, 'demo_inline_tag')
+  end
+end
+```
+
+**demo/_plugins/demo_block.rb**:
+
+```ruby
+require 'cgi'
+require 'jekyll_plugin_support'
+
+# Use the JekyllSupport module namespace so the self methods are automajically found
+module JekyllSupport
+  DemoBlockError = JekyllSupport.define_error
+
+  class DemoBlock < JekyllBlock
+    VERSION = '0.1.2'.freeze
+
+    def render_impl(text)
+      @demo_block_error = @helper.parameter_specified? 'raise_demo_block_error'
+      @keyword1         = @helper.parameter_specified? 'keyword1'
+      @keyword2         = @helper.parameter_specified? 'keyword2'
+      @name1            = @helper.parameter_specified? 'name1'
+      @name2            = @helper.parameter_specified? 'name2'
+      @standard_error   = @helper.parameter_specified? 'raise_standard_error'
+
+      if @tag_config
+        @die_on_demo_block_error = @tag_config['die_on_demo_block_error'] == true
+        @die_on_standard_error   = @tag_config['die_on_standard_error'] == true
+      end
+
+      raise DemoBlockTagError, 'This DemoBlockTagError error is expected.' if @demo_block_error
+      raise StandardError, 'This StandardError error is expected.' if @standard_error
+
+      # _infinity = 1 / 0 if @standard_error # Not required
+
+      output text
+    rescue DemoBlockTagError => e # jekyll_plugin_support handles StandardError
+      @logger.error { e.logger_message }
+      exit! 1 if @die_on_demo_block_error
+
+      e.html_message
+    end
+
+    private
+
+    def output(text)
+      <<~END_OUTPUT
+        <pre>@helper.tag_name=#{@helper.tag_name}
+
+        @mode=#{@mode}
+
+        # jekyll_plugin_support becomes able to perform variable substitution after this variable is defined.
+        # The value could be updated at a later stage, but no need to add that complexity unless there is a use case.
+        @argument_string="#{@argument_string}"
+
+        @helper.argv=
+          #{@helper.argv&.join("\n  ")}
+
+        # Liquid variable name/value pairs
+        @helper.params=
+          #{@helper.params&.map { |k, v| "#{k}=#{v}" }&.join("\n  ")}
+
+        # The keys_values property serves no purpose any more, consider it deprecated
+        @helper.keys_values=
+          #{(@helper.keys_values&.map { |k, v| "#{k}=#{v}" })&.join("\n  ")}
+
+        @helper.remaining_markup='#{@helper.remaining_markup}'
+
+        @envs=#{@envs.keys.sort.join(', ')}
+
+        @config['url']='#{@config['url']}'
+
+        @site.collection_names=#{@site.collection_names&.sort&.join(', ')}
+
+        @page['description']=#{@page['description']}
+
+        @page['path']=#{@page['path']}
+
+        @keyword1=#{@keyword1}
+
+        @keyword2=#{@keyword2}
+
+        @name1=#{@name1}
+
+        @name2=#{@name2}
+
+        text=#{text}</pre>
+      END_OUTPUT
+    end
+
+    JekyllPluginHelper.register(self, 'demo_block_tag')
+  end
+end
+```
+
+The following is an example of no_arg_parsing optimization.
+
+```ruby
+require 'jekyll_plugin_support'
+
+# Use the JekyllSupport module namespace so the self methods are automajically found
+module JekyllSupport
+  class DemoTagNoArgs < JekyllTagNoArgParsing
+    VERSION = '0.1.0'.freeze
+
+    def render_impl
+      <<~END_OUTPUT
+        The raw arguments passed to this <code>DemoTagNoArgs</code> instance are:<br>
+        <code>#{@argument_string}</code>
+      END_OUTPUT
+    end
+
+    JekyllPluginHelper.register(self, 'demo_inline_tag_no_arg')
+  end
+end
+```
 
 ### Run Freely
 
@@ -668,6 +1421,10 @@ It can be used to debug the plugin or to run freely.
 
  1. Set breakpoints in Visual Studio Code.
 
+ 2. Run the **Debug Demo development** or **Debug Demo production** launch configuration.
+
+Alternatively, you can:
+
  2. Initiate a debug session from the command line by running the `demo/_bin/debug` script:
 
     ```shell
@@ -694,7 +1451,7 @@ It can be used to debug the plugin or to run freely.
     ```
 
  3. Once the `DEBUGGER: wait for debugger connection...` message appears,
-    run the Visual Studio Code launch configuration called `Attach with rdbg`.
+    run the Visual Studio Code launch configuration called **Attach with rdbg**.
 
  4. View the generated website,
     which might be at [`http://localhost:4444`](http://localhost:4444),