jekyll_plugin_support 0.8.3 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9953a9a01da37cddcb43f16784ba12afbb90eeea9df7b7346b6593e7d7b483e
-  data.tar.gz: 69d7a9885fc9d3dfaa8308f8a4cfc989a42e3a0b6e5af76ce65a9b0b7dd081b1
+  metadata.gz: 20c575e857da7ffa50f37a587494b25232e1eb1309040946dd13d8f896250f07
+  data.tar.gz: 4aa5e163875f4e99adca9a6bc4ca97927c95c4cc4d017f52ca0b108d9ea24670
 SHA512:
-  metadata.gz: ca1c2618a298fda325a4aa4a4b9d62e1c16d1ead64c1737390aa73fdd4326f7c7d6f3830155a6c6aa7c286fc50ec376c8c4ffcd4ba6698b00f1ce85769217368
-  data.tar.gz: 32702f17fbfb0bcc87df9f6f7033b210adade31c67d29aaa4daa7ebc0d3c4677a885ec088404caa787f00697d4d81f1e017108e4fc6c2a5ec9f5f19a5c16839a
+  metadata.gz: f2a2123c073c9e344e097e3eecd364606037bdd0213045d7060a09d48acaac1810eb609e201126e3f4fc8e5edc0e4e6e81db43800aa4eea954490d4e21e91cdc
+  data.tar.gz: 2d4e8daa6ea71e412065356a7029f3ff0b432fb7a06cdc98f403ba02709106f75c62e8236bae12668e6b181f4c52ccba328811fdb9619cd075597fea622052e7

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Change Log
 
 
+## 0.8.5 / 2024-03-25
+
+* Empty block tags now return a value. See https://talk.jekyllrb.com/t/empty-liquid-block-not-rendering
+
+
+## 0.8.4 / 2024-02-27
+
+* Problem in error handler fixed.
+* A warning is logged if an environment variable is undefined and `die_if_undefined` is not set.
+
+
 ## 0.8.3 / 2024-01-05
 
 * Variables defined in front matter of layouts and pages are now handled.

data/README.md

@@ -26,6 +26,27 @@ Plugins that use `jekyll_plugin_support` include:
 [`jekyll_plugin_support`](https://github.com/mslinn/jekyll_plugin_support/tree/master/demo/_plugins)
 
 
+## Features
+
+Jekyll plugin tags created from `jekyll_plugin_support` framework automatically have the following features:
+
+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.
+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.
+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.
+
+
 ## Installation
 
 `Jekyll_plugin_support` is packaged as a Ruby gem.
@@ -297,11 +318,14 @@ 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.
 
 
-## Liquid Variable Definitions
+## Configuration Variables
 
 `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`.
+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.
+
 The following `_config.yml` fragment defines 3 variables called `var1`, `var2` and `var3`:
 
 ```yaml
@@ -312,18 +336,44 @@ liquid-vars:
 ```
 
 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.
+They are can be used like any other Liquid variable.
+
+
+### 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.
+However, plugins made from `jekyll_plugin_support` automatically
+expand all types of variable references passed as parameters and in block tag bodies.
 
-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.
+`Jekyll_plugin_support` tag and block plugins expand the following types of variables:
+
+* Jekyll_plugin_support configuration variables, discussed above.
+* Jekyll [page](https://jekyllrb.com/docs/variables/#page-variables) and
+  [layout](https://jekyllrb.com/docs/layouts/#variables) variables.
+* Inline Liquid variables (defined in [assign](https://shopify.dev/docs/api/liquid/tags/assign) and [capture](https://shopify.dev/docs/api/liquid/tags/capture) statements).
+
+In the following example web page, Jekyll expands the `var1` reference within the `<p></p>` tag,
+but not the `var1` or `var2` references passed to `my_plugin`.
 
 ```html
-This is the value of var1: {{var1}}.
+<p>This is the value of var1: {{var1}}.</p>
 
 {% my_plugin param1="{{var1}}" param2="{{var2}}" %}
 ```
 
+Assuming that `my_plugin` was written as a `jekyll_plugin_support` plugin,
+all variable references in its parameters are expanded.
+Thus, the above is interpreted as follows when `my_plugin` is evaluated during the Jekyll rendering process:
+</p>
+
+```html
+<p>This is the value of var1: value1.</p>
+
+{% my_plugin param1="value1" param2="value 2" %}
+```
+
+
 `Jekyll_plugin_support` expands most of the [plugin variables described above](#predefined-variables),
 replacing Liquid variable references with their values.
 The exception is `@argument_string`, which is not expanded.

data/lib/jekyll_plugin_error_handling.rb

@@ -35,7 +35,6 @@ module JekyllSupportErrorHandling
     string.gsub(/\e\[([;\d]+)?m/, '')
   end
 
-  # TODO: Delete this
   def maybe_reraise_error(error, throw_error: true)
     fmsg = format_error_message "#{error.class}: #{error.message.strip}"
     @logger.error { fmsg }

data/lib/jekyll_plugin_helper.rb

@@ -98,7 +98,7 @@ class JekyllPluginHelper
                             .parse(@argv_original)
     @params_original = @keys_values_original unless respond_to?(:no_arg_parsing) && no_arg_parsing
 
-    @argv = Shellwords.split(self.class.expand_env(markup))
+    @argv = Shellwords.split(self.class.expand_env(markup, logger))
     @keys_values = KeyValueParser
                    .new({}, { array_values: false, normalize_keys: false, separator: /=/ })
                    .parse(@argv)

data/lib/jekyll_plugin_helper_class.rb

@@ -5,12 +5,19 @@ require 'yaml'
 # Class methods for JekyllPluginHelper
 class JekyllPluginHelper
   # Expand an environment variable reference
-  def self.expand_env(str, die_if_undefined: false)
-    str&.gsub(/\$([a-zA-Z_][a-zA-Z0-9_]*)|\${\g<1>}|%\g<1>%/) do
+  def self.expand_env(str, logger = nil, die_if_undefined: false)
+    str&.gsub(/\$([a-zA-Z_][a-zA-Z0-9_]*)|\${\g<1>}/) do
       envar = Regexp.last_match(1)
-      raise JekyllPluginSupportError, "jekyll_plugin_support error: #{envar} is undefined".red, [] \
-        if !ENV.key?(envar) && die_if_undefined # Suppress stack trace
+      unless ENV.key? envar
+        msg = "jekyll_plugin_support error: environment variable #{envar} is undefined"
+        raise JekyllPluginSupportError, msg.red, [] if die_if_undefined
 
+        if logger
+          logger.warn msg
+        else
+          puts msg.red
+        end
+      end
       ENV.fetch(envar, nil)
     end
   end

data/lib/jekyll_plugin_support/version.rb

@@ -1,3 +1,3 @@
 module JekyllPluginSupportVersion
-  VERSION = '0.8.3'.freeze
+  VERSION = '0.8.5'.freeze
 end

data/lib/jekyll_plugin_support_block.rb

@@ -29,6 +29,12 @@ module JekyllSupport
       Jekyll::CustomError.factory @error_name
     end
 
+    # Liquid::Block subclasses do not render if there is no content within the tag
+    # This override fixes that
+    def blank?
+      false
+    end
+
     # Method prescribed by the Jekyll plugin lifecycle.
     # Defines @config, @envs, @mode, @page and @site
     # @return [String]
@@ -52,7 +58,7 @@ module JekyllSupport
 
       @mode = @config['env']&.key?('JEKYLL_ENV') ? @config['env']['JEKYLL_ENV'] : 'development'
 
-      @helper.reinitialize(@markup.strip)
+      @helper.reinitialize @markup.strip
 
       @attribution = @helper.parameter_specified?('attribution') || false unless @no_arg_parsing
       @logger.debug { "@keys_values='#{@keys_values}'" }
@@ -60,7 +66,7 @@ module JekyllSupport
       markup = JekyllSupport.lookup_liquid_variables liquid_context, @argument_string
       @helper.reinitialize markup
 
-      render_impl text
+      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}" }

data/lib/jekyll_plugin_support_tag.rb

@@ -63,7 +63,10 @@ module JekyllSupport
       render_impl
     rescue StandardError => e
       e.shorten_backtrace
-      @logger.error { "#{e.class} on line #{@line_number} of #{e.backtrace[0].split(':').first} while processing #{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
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.5
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-06 00:00:00.000000000 Z
+date: 2024-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Provides a framework for writing and testing Jekyll plugins