jekyll_plugin_support 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc8c02963da77be335a8e4713e9bcffc12395912733d31781e16198f9f9392f0
-  data.tar.gz: 8851a2ede60d7a70f0cb7eab711c7a3cb06da87d9764740d5dd50a385ee8066d
+  metadata.gz: b54badeb565b69fb6839140b7ce7b340d6a6663c226a3f7cb8728df2e0f61b2e
+  data.tar.gz: f74acdbe3c4d99561dead976deb36c4ff477f06dac7783a0ef918df901a71a53
 SHA512:
-  metadata.gz: 06b06073d76ba15d23d69d585d3148edd0e2adcd86ffc0b6d7982d2659989aad9da79b6adab83220c9c4299354e423a4bc3490ace1f2c1348d5e9a01e1b848c8
-  data.tar.gz: 9e9bd5db4569abe954ba547e38538c62ecf99037f772a893ef73a1fe68c9a9766df4c15069f6e1ff3aea578913d92e91922ab076c2be632540eb1e31a73e33a4
+  metadata.gz: d3deaa658d05e5f9cf629ba10a337f9b864465462a362d1d4670eaa3afff32c78b04cbc974a17fb9afd9fbac1392a2e4c58c1e0fbbd40a145ac9c4076b5a741a
+  data.tar.gz: 910ca35d862324baac1eb5c627662f4f4dac01e5966a06ad9c071bf1354800458ff81f16e260375680845d7062ee9dc7c41c63ab994f4d2630ad56eacbe8bb51

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change Log
 
+## 1.1.0 / 2025-02-07
+
+* Now replaces include and layout variables with their values
+* Renamed `@helper.markup` to `@helper.argument_string`
+* Improved `nil` handling throughout
+* Added the **Debug Demo production** launch configuration to debug the demo website in production mode
+* Added the `bin/release_port` script that kills hung processes being debugged
+* Added the `cleanDemo` task for the **Debug Demo production** and **Debug Demo development** tasks
+* Many minor improvements to the demo.
+* `JekyllSupport::JekyllPluginHelper::register` now accepts a `quiet` option, to suppress the signon message.
+  Use it like this:
+
+  ```ruby
+  JekyllPluginHelper.register(self, 'tag_name', quiet: true)
+  ```
+
+
+## 1.0.3 / 2024-08-19
+
+* Still fussing with error handling
+
 
 ## 1.0.2 / 2024-08-19
 
@@ -10,7 +31,7 @@
 
    ```ruby
     rescue DemoInlineTagError => e # jekyll_plugin_support handles StandardError
-      @logger.error e.logger_message
+      @logger.error { e.logger_message }
       exit! 1 if @die_on_demo_tag_error
 
       e.html_message

data/README.md

@@ -1,13 +1,17 @@
 # `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>
@@ -33,51 +37,70 @@ 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.
-
-In addition, a demonstration website is provided for easy testing of your plugins.
+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`.
 
 
 ## 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`
@@ -104,13 +127,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 +172,7 @@ 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.
 
 
 ## Predefined Plugin Variables
@@ -150,10 +181,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 +198,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 +355,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 +372,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 +477,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 +505,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 +536,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 +568,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 +714,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.
@@ -647,9 +778,203 @@ blah:
 
 ## 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 +993,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 +1023,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),

data/jekyll_plugin_support.gemspec

@@ -3,12 +3,12 @@ require_relative 'lib/jekyll_plugin_support/version'
 Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_plugin_support'
 
-  spec.bindir = 'exe'
-  spec.authors = ['Mike Slinn']
-  spec.email = ['mslinn@mslinn.com']
-  spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
+  spec.bindir   = 'exe'
+  spec.authors  = ['Mike Slinn']
+  spec.email    = ['mslinn@mslinn.com']
+  spec.files    = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
   spec.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_plugin_support.html'
-  spec.license = 'MIT'
+  spec.license  = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
     'bug_tracker_uri'   => "#{github}/issues",
@@ -16,17 +16,18 @@ Gem::Specification.new do |spec|
     'homepage_uri'      => spec.homepage,
     'source_code_uri'   => github,
   }
-  spec.name = 'jekyll_plugin_support'
+  spec.name                 = 'jekyll_plugin_support'
+  spec.platform             = Gem::Platform::RUBY
   spec.post_install_message = <<~END_MESSAGE
 
     Thanks for installing #{spec.name}!
 
   END_MESSAGE
-  spec.require_paths = ['lib']
+  spec.require_paths         = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
-  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
+  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
 
   spec.add_dependency 'facets'
   spec.add_dependency 'jekyll', '>= 3.5.0'

data/lib/block/jekyll_plugin_support_block.rb

@@ -8,16 +8,28 @@ module JekyllSupport
     # See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
     # @param tag_name [String] the name of the tag, which we usually know.
     # @param argument_string [String] the arguments passed to the tag, as a single string.
-    # @param parse_context [Liquid::ParseContext] hash that stores Liquid options.
-    #        By default it has two keys: :locale and :line_numbers, the first is a Liquid::I18n object, and the second,
-    #        a boolean parameter that determines if error messages should display the line number the error occurred.
-    #        This argument is used mostly to display localized error messages on Liquid built-in Tags and Filters.
-    #        See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    # @param parse_context [Liquid::ParseContext] contains the following attributes:
+    #        @depth might have the value 0
+    #        @error_mode might have the value `:strict`
+    #        @line_number duplicates @ptions[:line_number]
+    #        @locale duplicates @ptions[:locale]
+    #        @options is a hash with the following two keys that holds Liquid options:
+    #          :locale is a Liquid::I18n object, used to display localized error messages on Liquid built-in tags and filters.
+    #          :line_number is the line number containing the plugin invocation.
+    #          See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    #        @partial Boolean, unclear what this indicates
+    #        @template_options Replicates @options
+    #        @trim_whitespace might have the value `false`
+    #        @warnings array
     # @return [void]
     def initialize(tag_name, markup, parse_context)
       super
       @tag_name = tag_name
-      @argument_string = markup.to_s # Vars in plugin parameters cannot be replaced yet
+      raise JekyllPluginSupportError, "markup is a #{markup.class} with value '#{markup}'." unless markup.instance_of? String
+
+      # Lookup variable names with values in markup in render because site and config are not available here
+      @argument_string = markup # Replace variable names with values in markup in render because site and config are not available here
+
       @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
       @logger.debug { "#{self.class}: respond_to?(:no_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
       @helper = JekyllPluginHelper.new tag_name, markup, @logger, respond_to?(:no_arg_parsing)
@@ -36,11 +48,11 @@ module JekyllSupport
     # Defines @config, @envs, @mode, @page and @site
     # @return [String]
     def render(liquid_context)
-      @helper.liquid_context = JekyllSupport.inject_vars @logger, liquid_context
+      @helper.liquid_context = JekyllSupport.inject_config_vars liquid_context # modifies liquid_context
       text = super # Liquid variable values in content are looked up and substituted
 
       @envs      = liquid_context.environments.first
-      @page      = liquid_context.registers[:page] # hash
+      @page      = liquid_context.registers[:page]
       @scopes    = liquid_context.scopes
       @site      = liquid_context.registers[:site]
 
@@ -51,6 +63,7 @@ module JekyllSupport
 
       set_error_context
 
+      # @envs.keys are :content, :highlighter_prefix, :highlighter_suffix, :jekyll, :layout, :page, :paginator, :site, :theme
       @layout    = @envs[:layout]
       @paginator = @envs[:paginator]
       @theme     = @envs[:theme]
@@ -58,18 +71,23 @@ module JekyllSupport
       env = @config['env']
       @mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
 
-      @helper.reinitialize @markup.strip
+      @argument_string = JekyllSupport.lookup_liquid_variables @logger, @helper.liquid_context, @argument_string.to_s.strip
+      @helper.reinitialize @argument_string.to_s.strip
 
       @attribution = @helper.parameter_specified?('attribution') || false unless @no_arg_parsing
       @logger.debug { "@keys_values='#{@keys_values}'" }
 
-      markup = JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
-      @helper.reinitialize markup
+      # @argument_string = JekyllSupport.lookup_liquid_variables @logger, liquid_context, @argument_string # Is this redundant?
+      # @argument_string.strip! # Is this redundant?
+      # @helper.reinitialize @argument_string # Is this redundant?
 
       render_impl(text)
     rescue StandardError => e
       e.shorten_backtrace
-      @logger.error { "#{e.class} on line #{@line_number} of #{e.backtrace[0].split(':').first} by #{@tag_name} - #{e.message}" }
+      file_name = e.backtrace[0]&.split(':')&.first
+      in_file_name = "in '#{file_name}' " if file_name
+      of_page = "of '#{@page['path']}'" if @page
+      @logger.error { "#{e.class} on line #{@line_number} #{of_page} while processing #{tag_name} #{in_file_name}- #{e.message}" }
       binding.pry if @pry_on_standard_error # rubocop:disable Lint/Debugger
       raise e if @die_on_standard_error
 

data/lib/error/jekyll_custom_error.rb

@@ -16,14 +16,14 @@ module JekyllSupport
     end
 
     def calling_file
-      file_fq, _line_number, _extra = backtrace[0].split(':')
+      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
-      path, line_number, _caller = backtrace[1].split(':')
+      path, line_number, _caller = backtrace[1]&.split(':')
       <<~END_MSG
         <div class='#{error_name.snakecase}'>
           #{self.class} raised in #{calling_file} while processing line #{line_number} (after front matter) of #{path}
@@ -35,7 +35,7 @@ module JekyllSupport
     def logger_message
       shorten_backtrace
       kaller = caller(1..1).first
-      path, line_number, _caller = backtrace[1].split(':')
+      path, line_number, _caller = backtrace[1]&.split(':')
       <<~END_MSG
         #{error_name} raised in #{kaller} while processing line #{line_number} (after front matter) of #{path}
           #{message}

data/lib/error/jekyll_plugin_error_handling.rb

@@ -34,7 +34,7 @@ module JekyllSupportError
   end
 
   def maybe_reraise_error(error, throw_error: true)
-    fmsg = JekyllSupport.format_error_message "#{error.class}: #{error.message.strip}"
+    fmsg = format_error_message "#{error.class}: #{error.message.strip}"
     @logger.error { fmsg }
     return "<span class='jekyll_plugin_support_error'>#{fmsg}</span>" unless throw_error
 

data/lib/helper/jekyll_plugin_helper.rb

@@ -23,7 +23,7 @@ module JekyllSupport
       @tag_name = tag_name
       @logger = logger
       @no_arg_parsing = no_arg_parsing
-      @markup = markup
+      @argument_string = markup
     rescue StandardError => e
       e.shorten_backtrace
       @logger.error { e.message }
@@ -42,7 +42,7 @@ module JekyllSupport
 
     def reinitialize(markup)
       # @keys_values was a Hash[Symbol, String|Boolean] but now it is Hash[String, String|Boolean]
-      @markup = markup
+      @argument_string = markup
       if @no_arg_parsing
         define_singleton_method(:argv) { warn_fetch :argv }
         define_singleton_method(:keys_values) { warn_fetch :keys_values }

data/lib/helper/jekyll_plugin_helper_class.rb

@@ -55,7 +55,10 @@ module JekyllSupport
       END_MSG
     end
 
-    def self.register(klass, tag_name)
+    # @param klass [Class] class instance to register
+    # @param tag_name [String] name of plugin defined by klass to register as
+    # @param quiet [Boolean] suppress registration message if truthy
+    def self.register(klass, tag_name, quiet: false)
       abort("Error: The #{tag_name} plugin does not define VERSION") \
         unless klass.const_defined?(:VERSION)
 
@@ -67,6 +70,8 @@ module JekyllSupport
                 klass.ancestors.include?(JekyllSupport::JekyllTag))
 
       Liquid::Template.register_tag(tag_name, klass)
+      return if quiet
+
       msg = generate_message(klass, tag_name, version)
       PluginMetaLogger.instance.info { msg }
     end

data/lib/jekyll_plugin_support/jekyll_plugin_support_class.rb

@@ -39,23 +39,21 @@ module JekyllSupport
     END_MSG
   end
 
-  # Add variable definitions from _config.yml to liquid_context
-  # Modifies liquid_context in the caller
+  # Inject variable definitions from _config.yml into liquid_context
+  # Modifies liquid_context.scopes in the caller
   # (call by object reference, see https://stackoverflow.com/a/1872159/553865)
   # @return modified liquid_context
   # See README.md#configuration-variable-definitions
   # See demo/variables.html
-  def self.inject_vars(_logger, liquid_context)
-    # TODO: Modify a deep clone? Do I dare?
+  def self.inject_config_vars(liquid_context)
     site = liquid_context.registers[:site]
 
     plugin_variables = site.config['liquid_vars']
-    return liquid_context unless plugin_variables
 
     scope = liquid_context.scopes.last
 
     env = site.config['env']
-    mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
+    @mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
 
     # Set default values
     plugin_variables&.each do |name, value|
@@ -63,7 +61,7 @@ module JekyllSupport
     end
 
     # Override with environment-specific values
-    plugin_variables[mode]&.each do |name, value|
+    plugin_variables&.[](@mode)&.each do |name, value|
       scope[name] = value if value.instance_of? String
     end
 
@@ -85,34 +83,71 @@ module JekyllSupport
   # Modifies a clone of markup_original so variable references are replaced by their values
   # @param markup_original to be cloned
   # @return modified markup_original
-  def self.lookup_liquid_variables(liquid_context, markup_original)
+  def self.lookup_liquid_variables(logger, liquid_context, markup_original)
     markup = markup_original.clone
-    page = liquid_context.registers[:page]
+    page   = liquid_context.registers[:page]
     envs   = liquid_context.environments.first
     layout = envs[:layout]
 
-    # process layout variables
+    markup = process_layout_variables logger, layout, markup
+    markup = process_page_variables logger, page, markup
+    liquid_context.scopes&.each do |scope|
+      markup = process_included_variables logger, scope, markup
+      markup = process_liquid_variables logger, scope, markup
+    end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
+
+  def self.process_included_variables(logger, scope, markup)
+    scope['include']&.each do |name, value|
+      if value.nil?
+        value = ''
+        logger.warn { "include.#{name} is undefined." }
+      end
+      markup.gsub!("{{include.#{name}}}", value)
+    end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
+
+  def self.process_layout_variables(logger, layout, markup)
     layout&.each do |name, value|
+      if value.nil?
+        value = ''
+        logger.warn { "layout.#{value} is undefined." }
+      end
       markup.gsub!("{{layout.#{name}}}", value.to_s)
     end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
 
-    # process page variables
-    # puts "\nStarting page variable processing of #{page['path']}; stack has #{caller.length} elements".green
-    keys = page.keys
-    %w[excerpt output].each { |key| keys.delete key }
-    # puts "  Filtered keys: #{keys.join ' '}"
-    # keys.each { |key| puts "  #{key}: #{page[key]}" }
-    keys&.each do |key|
-      markup.gsub!("{{page.#{key}}}", page[key].to_s)
+  # Process assigned, captured and injected variables
+  def self.process_liquid_variables(logger, scope, markup)
+    scope&.each do |name, value|
+      next if name.nil?
+
+      value = '' if value.nil?
+      markup.gsub!("{{#{name}}}", value&.to_s)
     end
+    markup
+  rescue StandardError => e
+    logger.error { e.full_message }
+  end
 
-    # Process assigned, captured and injected variables
-    liquid_context.scopes.each do |scope|
-      scope&.each do |name, value|
-        markup.gsub!("{{#{name}}}", value.to_s)
-      end
+  def self.process_page_variables(logger, page, markup)
+    page&.each_key do |key|
+      next if %w[content excerpt next previous output].include? key # Skip problem attributes
+
+      markup.gsub!("{{page.#{key}}}", page[key].to_s)
     end
     markup
+  rescue StandardError => e
+    logger.error { e.full_message }
   end
 
   def self.warn_short_trace(logger, error)

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '1.0.2'.freeze
+  VERSION = '1.1.0'.freeze
 end

data/lib/jekyll_plugin_support.rb

@@ -3,7 +3,7 @@ require 'jekyll'
 require 'jekyll_plugin_logger'
 
 def require_directory(dir)
-  Dir[File.join(dir, '*.rb')].sort.each do |file|
+  Dir[File.join(dir, '*.rb')]&.sort&.each do |file|
     require file unless file == __FILE__
   end
 end

data/lib/tag/jekyll_plugin_support_tag.rb

@@ -9,18 +9,28 @@ module JekyllSupport
     # See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
     # @param tag_name [String] the name of the tag, which we usually know.
     # @param argument_string [String] the arguments passed to the tag, as a single string.
-    # @param parse_context [Liquid::ParseContext] hash that stores Liquid options.
-    #        By default it has two keys: :locale and :line_numbers, the first is a Liquid::I18n object, and the second,
-    #        a boolean parameter that determines if error messages should display the line number the error occurred.
-    #        This argument is used mostly to display localized error messages on Liquid built-in Tags and Filters.
-    #        See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    # @param parse_context [Liquid::ParseContext] contains the following attributes:
+    #        @depth might have the value 0
+    #        @error_mode might have the value `:strict`
+    #        @line_number duplicates @ptions[:line_number]
+    #        @locale duplicates @ptions[:locale]
+    #        @options is a hash with the following two keys that holds Liquid options:
+    #          :locale is a Liquid::I18n object, used to display localized error messages on Liquid built-in tags and filters.
+    #          :line_number is the line number containing the plugin invocation.
+    #          See https://github.com/Shopify/liquid/wiki/Liquid-for-Programmers#create-your-own-tags
+    #        @partial Boolean, unclear what this indicates
+    #        @template_options Replicates @options
+    #        @trim_whitespace might have the value `false`
+    #        @warnings array
     # @return [void]
     def initialize(tag_name, markup, parse_context)
       super
       @tag_name = tag_name
       raise JekyllPluginSupportError, "markup is a #{markup.class} with value '#{markup}'." unless markup.instance_of? String
 
-      @argument_string = markup
+      # Vars in plugin parameters cannot be replaced yet
+      @argument_string = markup.to_s # Lookup variable names with values in markup in render because site and config are not available here
+
       @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
       @logger.debug { "#{self.class}: respond_to?(:no_arg_parsing) #{respond_to?(:no_arg_parsing) ? 'yes' : 'no'}." }
       @helper = JekyllPluginHelper.new(tag_name, @argument_string, @logger, respond_to?(:no_arg_parsing))
@@ -33,7 +43,7 @@ module JekyllSupport
     def render(liquid_context)
       return if @helper.excerpt_caller
 
-      @helper.liquid_context = JekyllSupport.inject_vars @logger, liquid_context
+      @helper.liquid_context = JekyllSupport.inject_config_vars liquid_context # modifies liquid_context
 
       @envs      = liquid_context.environments.first
       @page      = liquid_context.registers[:page]
@@ -55,8 +65,12 @@ module JekyllSupport
       env = @config['env']
       @mode = env&.key?('JEKYLL_ENV') ? env['JEKYLL_ENV'] : 'development'
 
-      markup = JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
-      @helper.reinitialize markup.strip
+      @argument_string = JekyllSupport.lookup_liquid_variables @logger, @helper.liquid_context, @argument_string.to_s.strip
+      @helper.reinitialize @argument_string.to_s.strip
+
+      # @argument_string = JekyllSupport.lookup_liquid_variables @logger, liquid_context, @argument_string # Is this redundant?
+      # @argument_string.strip! # Is this redundant?
+      # @helper.reinitialize @argument_string # Is this redundant?
 
       render_impl
     rescue StandardError => e
@@ -64,13 +78,13 @@ module JekyllSupport
       file_name = e.backtrace[0]&.split(':')&.first
       in_file_name = "in '#{file_name}' " if file_name
       of_page = "of '#{@page['path']}'" if @page
-      @logger.error { "#{e.class} on line #{@line_number} #{of_page}while processing #{tag_name} #{in_file_name}- #{e.message}" }
+      @logger.error { "#{e.class} on line #{@line_number} #{of_page} while processing #{tag_name} #{in_file_name}- #{e.message}" }
       binding.pry if @pry_on_standard_error # rubocop:disable Lint/Debugger
       raise e if @die_on_standard_error
 
       <<~END_MSG
         <div class='standard_error'>
-          #{e.class} on line #{@line_number} of #{e.backtrace[0].split(':').first} while processing #{tag_name}: #{e.message}
+          #{e.class} on line #{@line_number} #{of_page} while processing #{tag_name} #{in_file_name} - #{JekyllPluginHelper.remove_html_tags e.message}
         </div>
       END_MSG
     end

data/spec/liquid_variable_parsing_spec.rb

@@ -8,12 +8,12 @@ class LiquidVariableParsing
   def variable_replace(str, scopes)
     result = str.clone
     match_data_list = str.to_enum(:scan, /{{[a-z_][a-zA-Z_0-9]*}}/).map { Regexp.last_match }.reverse
-    match_data_list.each do |md|
+    match_data_list&.each do |md|
       from = md.begin(0)
       to = md.end(0) - 1
       ref = str[from..to]
       name = ref[2..-3]
-      scopes.each do |scope|
+      scopes&.each do |scope|
         value = scope.key?(name) ? scope[name] : ref
         # puts "str=#{str}; from=#{from}; to=#{to}; name=#{name} value=#{value}"
         result[from..to] = value

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-19 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -80,7 +79,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - mslinn@mslinn.com
 executables: []
@@ -140,8 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Provides a framework for writing and testing Jekyll plugins
 test_files: