jekyll_plugin_support 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3264ff6310b66634f83d08ad21feab06f1bd871938fa11d4d72c2ab7be462f9c
-  data.tar.gz: aa2aacb039f82cb4fdec2821367254806683c39f0ba0dff1cdc715f37eb1577a
+  metadata.gz: 978c34638bfb0bae5b74952bb29d48dd15a8afe491406239fb05050efc78e5c2
+  data.tar.gz: fc570654d04aa4abdd8ed28fc551314fe36c0fb35ee1a14ce3ba98682298b084
 SHA512:
-  metadata.gz: 9e0487e0752e6ae0a9ba384e82b779a724cdc7733746c0b849fa9d2113f44b323b30d67a8d16933892b9b5221cdea990b53c4d7e93c1aecca354449c8bc6fbc7
-  data.tar.gz: 84989c8b7a0d10e37240fdb0f2f166e600d6aadb2d396e572e962e9c2541edef5d06509d991a82a252649e43089a00fe6a91b90545c34b7cf3ff9b113510fa15
+  metadata.gz: b1d27d2008c53695c6c2a2fa85b6519bf4f95a6106a84e7ff9ffd45b3f68187159d1a88cff4c4a3c9911b8c16f28c87f33696d41b75ddbf03c07ca6f7121ee0e
+  data.tar.gz: a4729e61ca106f2f5ee8ead49771dde0a08bd55ea96e254c4fe5efd1f49a8fe82f964eb68322cedadf7061f94a982626c686ef3d5ce22914a6761a03453e1f1a

data/.rubocop.yml

@@ -14,3 +14,6 @@ Layout/LineLength:
 
 Layout/MultilineMethodCallIndentation:
   Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,11 @@
-## 0.1.0 / 2023-01-10
-  * Initial version; only supports Jekyll block tags
+## 0.3.1 / 2023-02-07
+  * `JekyllBlock.render_impl` and `JekyllTag.render_impl` now define `@page` and `@site`.
+
+## 0.3.0 / 2023-01-14
+  * Added support for tags, which should subclass JekyllSupport::JekyllTag
 
 ## 0.2.0 / 2023-01-12
   * Refactored
+
+## 0.1.0 / 2023-01-10
+  * Initial version; only supports Jekyll block tags

data/README.md

@@ -2,21 +2,76 @@
 [![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.
-At present only Jekyll block tags are supported.
+`Jekyll_plugin_support` is a Ruby gem that facilitates writing and testing Jekyll plugins.
+At present, only Jekyll tags and blocks are supported.
 
 ## Installation
 
 Add this line to your Jekyll plugin's Gemfile:
 
 ```ruby
-gem 'jekyll_plugin_support'
+group :jekyll_plugins do
+  gem 'jekyll_plugin_support'
+end
 ```
 
 And then execute:
 
     $ bundle install
 
+## Usage
+`JekyllSupport::JekyllBlock` and `JekyllSupport::JekyllTag`
+provide support for Jekyll tag blocks and Jekyll tags, respectively.
+They are very 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`,
+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` 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 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):
+
+```ruby
+# For a tag:
+module Jekyll
+  class Quote < JekyllSupport::JekyllTag
+    def render_impl
+      site_data = @site.data
+      @break  = @helper.parameter_specified? 'break'
+      # ...
+    end
+  end
+end
+```
+
+```ruby
+# For a tag block:
+module Jekyll
+  class Quote < JekyllSupport::JekyllBlock
+    def render_impl(text)
+      site_url = @site.url
+      @break  = @helper.parameter_specified? 'break'
+      # ...
+    end
+  end
+end
+```
 
 ## Additional Information
 More information is available on

data/Rakefile

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 

data/jekyll_plugin_support.gemspec

@@ -1,8 +1,5 @@
-# frozen_string_literal: true
-
 require_relative 'lib/jekyll_plugin_support/version'
 
-# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_plugin_support'
 
@@ -47,4 +44,3 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rspec'
   spec.add_development_dependency 'ruby-debug-ide'
 end
-# rubocop:enable Metrics/BlockLength

data/lib/jekyll_plugin_support/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module JekyllQuoteVersion
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'.freeze
 end

data/lib/jekyll_plugin_support.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'jekyll'
 require 'jekyll_plugin_logger'
 require_relative 'jekyll_plugin_support_helper'
@@ -23,6 +21,7 @@ module JekyllSupport
     # @return [void]
     def initialize(tag_name, argument_string, parse_context)
       super
+      @tag_name = tag_name
       @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
       @helper = JekyllPluginHelper.new(tag_name, argument_string, @logger)
       @argument_string = argument_string
@@ -30,15 +29,53 @@ module JekyllSupport
 
     # Method prescribed by the Jekyll plugin lifecycle.
     # @return [String]
-    def render(context)
+    def render(liquid_context)
       text = super
+      @page = liquid_context.registers[:page]
+      @site = liquid_context.registers[:site]
       render_impl text
     end
 
     # Jekyll plugins should override this method, not render, so their plugin can be tested more easily
+    # @page and @site are available
     # @return [String]
     def render_impl(text)
       text
     end
   end
+
+  # Base class for Jekyll tags
+  class JekyllTag < Liquid::Tag
+    attr_reader :argument_string, :helper, :line_number, :logger, :page, :site
+
+    # 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
+    # @return [void]
+    def initialize(tag_name, argument_string, parse_context)
+      super
+      @tag_name = tag_name
+      @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+      @helper = JekyllPluginHelper.new(tag_name, argument_string, @logger)
+      @argument_string = argument_string
+    end
+
+    # Method prescribed by the Jekyll plugin lifecycle.
+    def render(liquid_context)
+      @page = liquid_context.registers[:page]
+      @site = liquid_context.registers[:site]
+      render_impl
+    end
+
+    # Jekyll plugins must override this method, not render, so their plugin can be tested more easily
+    # @page and @site are available
+    def render_impl
+      abort "JekyllTag render_impl for tag #{@tag_name} must be overridden, but it was not."
+    end
+  end
 end

data/lib/jekyll_plugin_support_spec_support.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'jekyll'
 
 Registers = Struct.new(:page, :site)

data/spec/{jekyll_plugin_support_spec.rb → jekyll_block_plugin_support_spec.rb}

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'jekyll_plugin_logger'
 # require 'rspec/match_ignoring_whitespace'
 require_relative '../lib/jekyll_plugin_support'

data/spec/jekyll_tag_plugin_support_spec.rb

@@ -0,0 +1,41 @@
+require 'jekyll_plugin_logger'
+# require 'rspec/match_ignoring_whitespace'
+require_relative '../lib/jekyll_plugin_support'
+require_relative '../lib/jekyll_plugin_support_spec_support'
+
+# Lets get this party started
+class MyTest
+  RSpec.describe JekyllSupport::JekyllTag do
+    let(:logger) do
+      PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+    end
+
+    let(:parse_context) { TestParseContext.new }
+
+    # Example for plugin authors to refer to:
+    #
+    # let(:helper) do
+    #   JekyllTagHelper.new(
+    #     'quote',
+    #     "cite='This is a citation' url='https://blah.com' This is the quoted text.",
+    #     logger
+    #   )
+    # end
+    #
+    # fit 'is created properly' do
+    #   command_line = "cite='This is a citation' url='https://blah.com' This is the quoted text.".dup
+    #   quote = Jekyll::Quote.send(
+    #     :new,
+    #     'quote',
+    #     command_line,
+    #     parse_context
+    #   )
+    #   result = quote.send(:render_impl, command_line)
+    #   expect(result).to match_ignoring_whitespace <<-END_RESULT
+    #     <div class='quote'>
+    #       This is the quoted text.
+    #     </div>
+    #   END_RESULT
+    # end
+  end
+end

data/spec/spec_helper.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'jekyll'
 require_relative '../lib/jekyll_plugin_support'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_plugin_support
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-12 00:00:00.000000000 Z
+date: 2023-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -139,9 +139,9 @@ files:
 - lib/jekyll_plugin_support/version.rb
 - lib/jekyll_plugin_support_helper.rb
 - lib/jekyll_plugin_support_spec_support.rb
-- spec/jekyll_plugin_support_spec.rb
+- spec/jekyll_block_plugin_support_spec.rb
+- spec/jekyll_tag_plugin_support_spec.rb
 - spec/spec_helper.rb
-- spec/status_persistence.txt
 homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#quote
 licenses:
 - MIT
@@ -174,7 +174,7 @@ signing_key:
 specification_version: 4
 summary: Provides support for writing Jekyll plugins.
 test_files:
-- spec/jekyll_plugin_support_spec.rb
+- spec/jekyll_block_plugin_support_spec.rb
+- spec/jekyll_tag_plugin_support_spec.rb
 - spec/spec_helper.rb
-- spec/status_persistence.txt
 ...