jekyll-highlight-cards 0.3.1

data/lib/jekyll-highlight-cards/polaroid_tag.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Liquid tag for creating styled polaroid photo components
+  #
+  # Syntax:
+  #   {% polaroid IMAGE_URL [size=WxH] [alt="..."] [title="..."] [link="..."] [archive="..."] %}
+  #
+  # Parameters:
+  #   - IMAGE_URL (required): Path or URL to the image (can be Liquid expression)
+  #   - size=WxH (optional): Image dimensions (e.g., size=300x200, size=400x, size=x300)
+  #   - alt="..." (optional): Alt text for the image (can be Liquid expression)
+  #   - title="..." (optional): Title text to display (can be Liquid expression, also used as alt fallback)
+  #   - link="..." (optional): URL to link to (can be Liquid expression)
+  #   - archive="..." (optional): Archive URL or "none" to opt out
+  #
+  # Note: Alt text priority: alt parameter > title parameter > empty string
+  #       This allows setting alt text without a visible title for accessibility
+  #
+  # Examples:
+  #   {% polaroid /assets/img/photo.jpg %}
+  #   {% polaroid /img/photo.jpg size=300x200 title="My Photo" %}
+  #   {% polaroid /img/photo.jpg alt="Screen reader description" %}
+  #   {% polaroid /img/photo.jpg alt="Detailed alt" title="Short Title" %}
+  #   {% polaroid {{ page.image }} size=x400 title={{ page.title }} %}
+  #   {% polaroid /img.jpg link="https://example.com" archive="none" %}
+  class PolaroidTag < Liquid::Tag
+    include ArchiveHelper
+    include DimensionParser
+    include ExpressionEvaluator
+    include TemplateRenderer
+
+    # Initialize the tag
+    #
+    # @param tag_name [String] the name of the tag
+    # @param markup [String] the tag markup containing parameters
+    # @param tokens [Array] parse tokens (unused)
+    def initialize(tag_name, markup, tokens)
+      super
+      @markup = markup.strip
+    end
+
+    # Render the polaroid tag
+    #
+    # @param context [Liquid::Context] the Liquid rendering context
+    # @return [String] rendered HTML
+    def render(context)
+      # Parse markup
+      params = parse_markup(@markup, context)
+
+      # Validate required image_url
+      raise ArgumentError, "polaroid tag requires an image URL" if params[:image_url].nil? || params[:image_url].empty?
+
+      # Parse size parameter if present
+      width, height = parse_dimensions(params[:size]) if params[:size]
+
+      # Determine link URL (defaults to image URL)
+      # Track if link was explicitly provided
+      explicit_link = !params[:link].nil? && !params[:link].empty?
+      link_url = params[:link] || params[:image_url]
+
+      # Resolve archive URL (archives the link URL, not the image)
+      archive_url = resolve_archive(params[:archive], context, link_url)
+
+      # Build template variables
+      variables = build_template_variables(
+        params[:image_url],
+        width,
+        height,
+        params[:title],
+        params[:alt],
+        link_url,
+        explicit_link,
+        archive_url
+      )
+
+      # Get site from context
+      site = context.registers[:site]
+
+      # Render template
+      render_template(site, "polaroid", variables)
+    end
+
+    private
+
+    # Parse the tag markup into image_url and named parameters
+    #
+    # @param markup [String] the tag markup
+    # @param context [Liquid::Context] the Liquid context
+    # @return [Hash] parsed parameters
+    def parse_markup(markup, context)
+      # Split by whitespace, keeping quoted strings and Liquid expressions together
+      # Handles escaped quotes (\") and backslashes (\\) within quoted strings
+      tokens = []
+      current = ""
+      in_quotes = false
+      quote_char = nil
+      in_liquid = 0
+      escaped = false
+
+      markup.each_char do |char|
+        # Handle escape sequences when in quotes
+        if escaped
+          current += char # Add the escaped character directly
+          escaped = false
+          next
+        end
+
+        # Check for escape character when in quotes
+        if char == "\\" && in_quotes
+          escaped = true
+          next # Don't add backslash to output, it's just the escape marker
+        end
+
+        # Track Liquid expression boundaries
+        if char == "{" && !in_quotes
+          in_liquid += 1
+          current += char
+        elsif char == "}" && !in_quotes && in_liquid.positive?
+          in_liquid -= 1
+          current += char
+        # Track quote boundaries
+        elsif ['"', "'"].include?(char) && !in_quotes && in_liquid.zero?
+          in_quotes = true
+          quote_char = char
+          current += char
+        elsif char == quote_char && in_quotes
+          in_quotes = false
+          current += char
+          quote_char = nil
+        # Split on whitespace only if not in quotes or Liquid expression
+        elsif char.match?(/\s/) && !in_quotes && in_liquid.zero?
+          tokens << current unless current.empty?
+          current = ""
+        else
+          current += char
+        end
+      end
+      tokens << current unless current.empty?
+
+      # First token is image URL (required)
+      image_url_token = tokens.shift
+      image_url = evaluate_expression(image_url_token, context, allow_nil: false)
+
+      # Parse remaining tokens as key=value pairs
+      result = { image_url: image_url }
+      tokens.each do |token|
+        next unless token =~ /^(\w+)=(.+)$/
+
+        key = Regexp.last_match(1).to_sym
+        value_token = Regexp.last_match(2)
+
+        # Evaluate value as Liquid expression
+        result[key] = evaluate_expression(value_token, context, allow_nil: true)
+      end
+
+      result
+    end
+
+    # Resolve archive URL (may be explicit, auto-lookup, or opt-out)
+    #
+    # @param source [String, nil] the archive source
+    # @param context [Liquid::Context] the Liquid context (unused but kept for consistency)
+    # @param url [String] the target URL to archive
+    # @return [String, nil] resolved archive URL
+    def resolve_archive(source, context, url)
+      # Check for explicit opt-out
+      return nil if source&.downcase == "none"
+
+      # Check for explicit archive URL
+      return evaluate_expression(source, context, allow_nil: true) if source && !source.empty?
+
+      # Auto-lookup if enabled (archives the link URL, not the image)
+      return archive_url_for(url) if archive_enabled?
+
+      nil
+    end
+
+    # Build template variables hash for rendering
+    #
+    # @param image_url [String] the image URL
+    # @param width [String, nil] the image width
+    # @param height [String, nil] the image height
+    # @param title [String, nil] the title text
+    # @param alt [String, nil] the alt text for the image
+    # @param link_url [String] the link URL
+    # @param explicit_link [Boolean] whether link was explicitly provided
+    # @param archive_url [String, nil] the archive URL
+    # @return [Hash] template variables with raw and escaped versions
+    def build_template_variables(image_url, width, height, title, alt, link_url, explicit_link, archive_url)
+      # Only set link_display if link was explicitly provided (not defaulted to image)
+      link_display = explicit_link && link_url ? strip_protocol(link_url) : nil
+
+      {
+        "image_url" => image_url,
+        "link_url" => link_url,
+        "title" => title,
+        "alt" => alt,
+        "link_display" => link_display,
+        "archive_url" => archive_url,
+        "width" => width,
+        "height" => height,
+        "escaped_image_url" => CGI.escapeHTML(image_url),
+        "escaped_link_url" => link_url ? CGI.escapeHTML(link_url) : nil,
+        "escaped_title" => title && !title.empty? ? CGI.escapeHTML(title) : "&nbsp;",
+        "escaped_alt" => alt && !alt.empty? ? CGI.escapeHTML(alt) : "",
+        "escaped_link_display" => link_display && !link_display.empty? ? CGI.escapeHTML(link_display) : "&nbsp;",
+        "escaped_archive_url" => archive_url ? CGI.escapeHTML(archive_url) : nil
+      }
+    end
+
+    # Strip protocol from URL for display
+    #
+    # @param url [String] the URL
+    # @return [String] URL without protocol
+    def strip_protocol(url)
+      url.sub(%r{^https?://}, "")
+    end
+  end
+end
+
+# Register the tag with Liquid
+Liquid::Template.register_tag("polaroid", JekyllHighlightCards::PolaroidTag)

data/lib/jekyll-highlight-cards/template_renderer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Custom exception for template not found errors
+  class TemplateNotFoundError < StandardError; end
+
+  # Custom exception for template rendering errors
+  class TemplateRenderError < StandardError; end
+
+  # Module for rendering Liquid templates with user override support
+  module TemplateRenderer
+    # Render a template with given variables
+    #
+    # @param site [Jekyll::Site] the Jekyll site object
+    # @param template_name [String] template name (e.g., "linkcard", "polaroid")
+    # @param variables [Hash] variables to pass to template
+    # @return [String] rendered HTML
+    # @raise [TemplateNotFoundError] if template file not found
+    # @raise [TemplateRenderError] if template rendering fails
+    def render_template(site, template_name, variables)
+      template_path = find_template_path(site, template_name)
+
+      raise TemplateNotFoundError, "Template not found: #{template_name}" if template_path.nil?
+
+      begin
+        template_content = File.read(template_path)
+        template = Liquid::Template.parse(template_content)
+        template.render(variables)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise TemplateRenderError, "Failed to read template '#{template_name}' at #{template_path}: #{e.message}"
+      rescue Encoding::InvalidByteSequenceError => e
+        raise TemplateRenderError, "Invalid encoding in template '#{template_name}' at #{template_path}: #{e.message}"
+      rescue Liquid::SyntaxError, Liquid::Error => e
+        raise TemplateRenderError, "Liquid error in template '#{template_name}': #{e.message}"
+      rescue StandardError => e
+        raise TemplateRenderError, "Unexpected error rendering template '#{template_name}': #{e.message}"
+      end
+    end
+
+    # Find template file path, checking user override first, then gem default
+    #
+    # @param site [Jekyll::Site] the Jekyll site object
+    # @param template_name [String] template name without .html extension
+    # @return [String, nil] path to template file or nil if not found
+    # @raise [ArgumentError] if template_name contains invalid characters
+    def find_template_path(site, template_name)
+      validate_template_name!(template_name)
+
+      template_filename = "#{template_name}.html"
+      relative_path = File.join("highlight-cards", template_filename)
+
+      # Check for user override first
+      user_path = find_user_template(site, relative_path)
+      return user_path if user_path
+
+      # Fall back to gem bundled template
+      find_gem_template(relative_path)
+    end
+
+    private
+
+    # Validate template name to prevent path traversal attacks
+    #
+    # @param template_name [String] the template name to validate
+    # @raise [ArgumentError] if template_name contains invalid characters
+    def validate_template_name!(template_name)
+      return if template_name.match?(/\A[A-Za-z0-9_-]+\z/)
+
+      raise ArgumentError, "Invalid template name: #{template_name}. " \
+                           "Must contain only letters, numbers, hyphens, and underscores."
+    end
+
+    # Find template in user's site _includes directory
+    #
+    # @param site [Jekyll::Site] the Jekyll site object
+    # @param relative_path [String] relative path to template
+    # @return [String, nil] path to template or nil
+    def find_user_template(site, relative_path)
+      return nil unless site&.source
+
+      includes_dir = File.join(site.source, "_includes")
+      template_path = File.join(includes_dir, relative_path)
+
+      safe_template_path(includes_dir, template_path)
+    end
+
+    # Find template in gem's bundled _includes directory
+    #
+    # @param relative_path [String] relative path to template
+    # @return [String, nil] path to template or nil
+    def find_gem_template(relative_path)
+      gem_root = File.expand_path("../..", __dir__)
+      includes_dir = File.join(gem_root, "_includes")
+      template_path = File.join(includes_dir, relative_path)
+
+      safe_template_path(includes_dir, template_path)
+    end
+
+    # Verify template path is safe (within allowed directory)
+    #
+    # @param allowed_dir [String] the allowed base directory
+    # @param template_path [String] the template path to check
+    # @return [String, nil] template path if safe, nil otherwise
+    def safe_template_path(allowed_dir, template_path)
+      return nil unless File.exist?(template_path)
+
+      expanded_dir = File.expand_path(allowed_dir)
+      expanded_path = File.expand_path(template_path)
+
+      expanded_path.start_with?(expanded_dir) ? template_path : nil
+    end
+  end
+end

data/lib/jekyll-highlight-cards/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  VERSION = "0.3.1"
+end

data/lib/jekyll-highlight-cards.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "liquid"
+require "cgi"
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "jekyll-highlight-cards/version"
+require_relative "jekyll-highlight-cards/dimension_parser"
+require_relative "jekyll-highlight-cards/expression_evaluator"
+require_relative "jekyll-highlight-cards/archive_helper"
+require_relative "jekyll-highlight-cards/template_renderer"
+
+# Require tags and hooks
+require_relative "jekyll-highlight-cards/linkcard_tag"
+require_relative "jekyll-highlight-cards/polaroid_tag"
+require_relative "jekyll-highlight-cards/image_sizing_hooks"
+
+# jekyll-highlight-cards: Styled card components for Jekyll
+#
+# This gem provides:
+# - {LinkcardTag}: `{% linkcard %}` Liquid tag for styled link cards
+# - {PolaroidTag}: `{% polaroid %}` Liquid tag for polaroid-style image cards
+# - {ImageSizingHooks}: Markdown image sizing syntax `![alt](img.jpg =300x200)`
+# - {ArchiveHelper}: Internet Archive integration with caching
+#
+# @example Basic linkcard usage
+#   {% linkcard https://example.com My Title %}
+#
+# @example Basic polaroid usage
+#   {% polaroid /assets/image.jpg size=300x200 title="Photo" %}
+#
+# @example Markdown image sizing
+#   ![Alt text](image.jpg =400x300)
+#
+# @see README.md Full usage documentation
+module JekyllHighlightCards
+
+  # 1. Define the path to SCSS files relative to this Ruby file
+  SASS_PATH = File.join(File.dirname(__FILE__), "../_sass")
+
+  # 2. Register a hook to run after Jekyll initializes
+  Jekyll::Hooks.register :site, :after_init do |site|
+    
+    # Ensure the 'sass' and 'load_paths' config keys exist
+    site.config["sass"] ||= {}
+    site.config["sass"]["load_paths"] ||= []
+
+    # 3. Append your plugin's path to the load_paths array
+    # We check first to avoid adding it multiple times (e.g. in watch mode)
+    unless site.config["sass"]["load_paths"].include?(SASS_PATH)
+      site.config["sass"]["load_paths"] << SASS_PATH
+    end      
+  end
+end

data/release-please-config.json

@@ -0,0 +1,12 @@
+{
+    "release-type": "ruby",
+    "bump-minor-pre-major": true,
+    "bump-patch-for-minor-pre-major": false,
+    "include-component-in-tag": false,
+    "packages": {
+        ".": {
+            "version-file": "lib/jekyll-highlight-cards/version.rb",
+            "pull-request-header": ":service_dog: I have created a release \\*bark\\* \\*woof\\*"
+        }
+    }
+}

metadata

@@ -0,0 +1,234 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-highlight-cards
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+platform: ruby
+authors:
+- Texarkanine
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.20'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Jekyll gem that provides two Liquid tags (linkcard and polaroid) for
+  creating styled card components with integrated Internet Archive functionality and
+  image sizing. Also includes Markdown image sizing hooks.
+email:
+- texarkanine@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".cursorignore"
+- ".github/workflows/ci.yaml"
+- ".github/workflows/release-please.yaml"
+- ".github/workflows/update-gemfile-lock.yaml"
+- ".gitignore"
+- ".release-please-manifest.json"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- _includes/highlight-cards/linkcard.html
+- _includes/highlight-cards/polaroid.html
+- _sass/_highlight-cards.scss
+- docs/linkcard-example.jpg
+- docs/polaroid-example.jpg
+- docs/polaroid-sidebyside-example.jpg
+- docs/polaroid-stacked-example.jpg
+- jekyll-highlight-cards.gemspec
+- lib/jekyll-highlight-cards.rb
+- lib/jekyll-highlight-cards/archive_helper.rb
+- lib/jekyll-highlight-cards/dimension_parser.rb
+- lib/jekyll-highlight-cards/expression_evaluator.rb
+- lib/jekyll-highlight-cards/image_sizing_hooks.rb
+- lib/jekyll-highlight-cards/linkcard_tag.rb
+- lib/jekyll-highlight-cards/polaroid_tag.rb
+- lib/jekyll-highlight-cards/template_renderer.rb
+- lib/jekyll-highlight-cards/version.rb
+- release-please-config.json
+homepage: https://github.com/texarkanine/jekyll-highlight-cards
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/texarkanine/jekyll-highlight-cards
+  source_code_uri: https://github.com/texarkanine/jekyll-highlight-cards
+  changelog_uri: https://github.com/texarkanine/jekyll-highlight-cards/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Jekyll plugin providing linkcard and polaroid Liquid tags with archive integration
+test_files: []