jekyll-tabler 0.1.0 → 0.1.1

data/lib/jekyll-tabler.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Copyright (c) 2026 phothinmg
+# <https://github.com/phothinmg/jekyll-tabler>
+
 require "jekyll"
 require "fileutils"
 require "shellwords"
@@ -7,8 +10,20 @@ require "yaml"
 
 require_relative "version"
 
+# Main plugin entrypoint.
+#
+# Flow overview for maintainers:
+# 1. This file is required by Jekyll when the plugin is listed in `_config.yml`.
+# 2. The two Liquid tags are registered at the bottom of the file.
+# 3. When Jekyll parses a page containing `{% tabler %}` or
+#    `{% tabler_filled %}`, Liquid instantiates the matching tag class and
+#    runs `initialize` once to parse the markup.
+# 4. During page rendering, Liquid calls `render`, which resolves literal
+#    values or Liquid variables from the page context.
+# 5. The resolved icon name is looked up in the packaged YAML asset and then
+#    wrapped in SVG markup for the final HTML output.
 module Jekyll
-  # module Jekyll::Tabler
+  # Shared helpers and Liquid tag implementations for Tabler icons.
   module Tabler
     VARIABLE_LOOKUP = /\A[a-zA-Z_][\w-]*(?:\.[\w-]+|\[[^\]]+\])*\z/
     OPTION_LOOKUP = /\A([^=\s]+)=(.+)\z/
@@ -16,6 +31,10 @@ module Jekyll
 
     module_function
 
+    # Loads the icon path data that ships with the gem.
+    #
+    # The YAML files map an icon name to one or more SVG path definitions.
+    # This is the only place where the plugin reaches into packaged assets.
     def tabler_icons(type)
       data_path = File.join(
         Gem.loaded_specs["jekyll-tabler"].full_gem_path,
@@ -25,6 +44,7 @@ module Jekyll
       YAML.load_file(data_path)
     end
 
+    # Builds the outline SVG after render-time values have been resolved.
     def outline_wrapper(icon_name, size = 24, color = "currentColor") # rubocop:disable Metrics/MethodLength
       icons = tabler_icons("outline")
       ds = Array(icons[icon_name])
@@ -47,6 +67,7 @@ module Jekyll
       HTML
     end
 
+    # Builds the filled SVG after render-time values have been resolved.
     def filled_wrapper(icon_name, size = 24, color = "currentColor") # rubocop:disable Metrics/MethodLength
       icons = tabler_icons("filled")
       ds = Array(icons[icon_name])
@@ -54,7 +75,7 @@ module Jekyll
       <<~HTML
         <svg xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 24 24"
-         width="#{size}"
+        width="#{size}"
         height="#{size}"
         fill="#{color}"
         class="jekyll-tabler-icon #{icon_name}"
@@ -65,6 +86,9 @@ module Jekyll
       HTML
     end
 
+    # Resolves a tag argument against the Liquid context when it looks like a
+    # variable lookup. Literal values such as `24` or `currentColor` pass
+    # through unchanged.
     def resolve_argument(argument, context)
       return argument unless argument.is_a?(String) && argument.match?(VARIABLE_LOOKUP)
 
@@ -72,10 +96,15 @@ module Jekyll
       resolved.nil? ? argument : resolved
     end
 
+    # Shared syntax error message used by both tags.
     def syntax_message
       "Syntax: {% tabler|tabler_filled icon_name [size] [color] [size=value] [color=value] %}"
     end
 
+    # Splits optional arguments into named options and positional arguments.
+    #
+    # Named options are validated here so each tag class can keep its
+    # initializer focused on assigning the final values.
     def parse_optional_args(arguments) # rubocop:disable Metrics/MethodLength
       arguments.each_with_object([{}, []]) do |argument, memo|
         options = memo[0]
@@ -95,7 +124,11 @@ module Jekyll
       end
     end
 
-    # class Jekyll::Tabler::OutlineTag
+    # Handles `{% tabler ... %}` tags.
+    #
+    # `initialize` runs during Liquid parsing, not page rendering, so this
+    # method only stores raw arguments. Variable resolution happens later in
+    # `render` when the page context is available.
     class OutlineTag < Liquid::Tag
       def initialize(tag_name, markup, tokens) # rubocop:disable Metrics/AbcSize
         super
@@ -114,6 +147,8 @@ module Jekyll
         raise Liquid::SyntaxError, e.message
       end
 
+      # Converts stored arguments into final values for the current page and
+      # delegates SVG generation to the shared helper.
       def render(context)
         icon_name = Jekyll::Tabler.resolve_argument(@icon_name, context)
         size = Jekyll::Tabler.resolve_argument(@size, context)
@@ -123,7 +158,10 @@ module Jekyll
       end
     end
 
-    # class Jekyll::Tabler::OutlineTag
+    # Handles `{% tabler_filled ... %}` tags.
+    #
+    # The control flow mirrors `OutlineTag`; the only behavior difference is
+    # the final SVG wrapper that uses filled icon data.
     class FilledTag < Liquid::Tag
       def initialize(tag_name, markup, tokens) # rubocop:disable Metrics/AbcSize
         super
@@ -142,6 +180,8 @@ module Jekyll
         raise Liquid::SyntaxError, e.message
       end
 
+      # Converts stored arguments into final values for the current page and
+      # delegates SVG generation to the shared helper.
       def render(context)
         icon_name = Jekyll::Tabler.resolve_argument(@icon_name, context)
         size = Jekyll::Tabler.resolve_argument(@size, context)
@@ -153,5 +193,7 @@ module Jekyll
   end
 end
 
+# Register the Liquid tags once on load so Jekyll can resolve them while
+# parsing site templates.
 Liquid::Template.register_tag("tabler", Jekyll::Tabler::OutlineTag)
 Liquid::Template.register_tag("tabler_filled", Jekyll::Tabler::FilledTag)

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Tabler
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-tabler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - phothinmg