jekyll-highlight-cards 0.3.1

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Evaluate Liquid expressions and handle string values
+  #
+  # Provides utilities for evaluating Liquid variables (e.g., `{{ page.title }}`)
+  # and processing string values with quote stripping and fallback behavior.
+  #
+  # @example Evaluate a Liquid variable
+  #   result = evaluate_expression("{{ page.title }}", context)
+  #
+  # @example Evaluate a quoted string
+  #   result = evaluate_expression('"My Title"', context)  #=> "My Title"
+  module ExpressionEvaluator
+    # Evaluate a token as a Liquid expression or literal string
+    #
+    # @param token [String] the token to evaluate
+    # @param context [Liquid::Context] the Liquid context for variable resolution
+    # @param allow_nil [Boolean] whether to allow nil results
+    # @return [String, nil] evaluated value or nil if evaluation fails
+    def evaluate_expression(token, context, allow_nil: true)
+      return nil if token.nil?
+      return "" if token.empty?
+
+      # Strip outer quotes if present
+      stripped = strip_outer_quotes(token)
+
+      # If the original token was quoted, treat as literal string
+      if stripped != token
+        return stripped if allow_nil
+
+        return stripped.empty? ? nil : stripped
+      end
+
+      # Try to evaluate as Liquid expression
+      if variable_lookup?(token)
+        begin
+          # Parse and evaluate the Liquid expression
+          template = Liquid::Template.parse(token)
+          result = template.render(context)
+          return result if allow_nil
+
+          return result.to_s.empty? ? nil : result
+        rescue Liquid::SyntaxError, StandardError => e
+          log_debug("Failed to evaluate '#{token}' as Liquid expression: #{e.message}")
+          # Fall back to literal string
+          return token if allow_nil
+
+          return token.empty? ? nil : token
+        end
+      end
+
+      # Return as literal string
+      return token if allow_nil
+
+      token.empty? ? nil : token
+    end
+
+    # Check if an expression looks like a Liquid variable lookup
+    #
+    # @param expression [String] the expression to check
+    # @return [Boolean] true if expression contains Liquid syntax
+    def variable_lookup?(expression)
+      return false if expression.nil? || expression.empty?
+
+      expression.include?("{{") || expression.include?("{%")
+    end
+
+    # Strip outer quotes from a string (both single and double quotes)
+    #
+    # @param value [String] the string to process
+    # @return [String] string with outer quotes removed if present
+    def strip_outer_quotes(value)
+      return value if value.nil? || value.empty?
+
+      # Check for matching outer quotes
+      if ((value.start_with?('"') && value.end_with?('"')) ||
+         (value.start_with?("'") && value.end_with?("'"))) && (value.length > 1)
+        return value[1..-2]
+      end
+
+      value
+    end
+
+    # Log debug message
+    #
+    # @param message [String] message to log
+    def log_debug(message)
+      Jekyll.logger.debug("HighlightCards:", message)
+    end
+
+    # Log info message
+    #
+    # @param message [String] message to log
+    def log_info(message)
+      Jekyll.logger.info("HighlightCards:", message)
+    end
+
+    # Log warning message
+    #
+    # @param message [String] message to log
+    def log_warn(message)
+      Jekyll.logger.warn("HighlightCards:", message)
+    end
+
+    # Log error message
+    #
+    # @param message [String] message to log
+    def log_error(message)
+      Jekyll.logger.error("HighlightCards:", message)
+    end
+  end
+end

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Jekyll hooks for Markdown image sizing syntax
+  #
+  # Extends standard Markdown image syntax with dimension specifiers:
+  # `![alt](image.jpg =300x200)`
+  #
+  # Automatically wraps sized images in links to themselves and applies
+  # width/height attributes. Skips images in code blocks.
+  #
+  # @example Basic sizing
+  #   ![Photo](image.jpg =300x200)
+  #
+  # @example Width only
+  #   ![Photo](image.jpg =400x)
+  #
+  # @example Height only
+  #   ![Photo](image.jpg =x300)
+  #
+  # @note Images inside code fences and inline code are not processed
+  # @note Sized images are automatically wrapped in <a> tags (if not already)
+  module ImageSizingHooks
+    extend DimensionParser
+
+    # Process document content before rendering
+    # Converts ![alt](src =WxH) to ![alt](src)<!-- IMG_SIZE:W:H -->
+    #
+    # @param document [Jekyll::Document] the document being processed
+    def self.process_pre_render(document)
+      content = document.content
+      return unless content
+
+      lines = content.lines
+      result = []
+
+      lines.each_with_index do |line, idx|
+        # Skip lines in code fences
+        if in_code_fence?(lines, idx)
+          result << line
+          next
+        end
+
+        # Process the line to convert sized images
+        processed_line = line.dup
+
+        # Match ![alt](src =dimensions) pattern
+        # Use gsub with block to check each match
+        processed_line.gsub!(/!\[([^\]]*)\]\(([^)]+)\s+=([^)]+)\)/) do |match|
+          match_start = Regexp.last_match.begin(0)
+
+          # Skip if inside inline code
+          if in_inline_code?(line, match_start)
+            match
+          else
+            alt = Regexp.last_match(1)
+            src = Regexp.last_match(2).strip
+            size = Regexp.last_match(3).strip
+
+            # Parse dimensions using DimensionParser
+            width, height = parse_dimensions(size)
+
+            # Build marker comment
+            "![#{alt}](#{src})<!-- IMG_SIZE:#{width}:#{height} -->"
+          end
+        end
+
+        result << processed_line
+      end
+
+      document.content = result.join
+    end
+
+    # Process document content after rendering
+    # Applies width/height attributes and auto-links sized images
+    #
+    # @param document [Jekyll::Document] the document being processed
+    def self.process_post_render(document)
+      output = document.output
+      return unless output
+
+      # Duplicate to avoid frozen string errors
+      output = output.dup
+
+      # Match <img><!-- IMG_SIZE:W:H --> patterns
+      output.gsub!(/(<img\s+[^>]*>)\s*<!--\s*IMG_SIZE:([^:]*):([^:]*)\s*-->/) do
+        img_tag = Regexp.last_match(1)
+        width = Regexp.last_match(2).to_s.strip
+        height = Regexp.last_match(3).to_s.strip
+
+        # Build attributes to add
+        attrs = []
+        attrs << %(width="#{width}") unless width.to_s.empty?
+        attrs << %(height="#{height}") unless height.to_s.empty?
+
+        # Add attributes to img tag
+        modified_img = if attrs.any?
+                         img_tag.sub("<img", "<img #{attrs.join(" ")}")
+                       else
+                         img_tag
+                       end
+
+        # Extract src for auto-linking
+        src = img_tag[/src=["']([^"']+)["']/, 1]
+
+        # Skip auto-linking if src is missing or malformed
+        next modified_img if src.nil? || src.empty?
+
+        # Check if image is already in a link (look back in output)
+        # Simple heuristic: check if there's an <a> tag before this image without a closing </a>
+        img_position = Regexp.last_match.begin(0)
+        prefix = output[0...img_position]
+
+        # Count <a> and </a> tags before this image
+        open_count = prefix.scan(/<a\s+/).length
+        close_count = prefix.scan(%r{</a>}).length
+        already_linked = (open_count > close_count)
+
+        # Auto-link if not already linked
+        if already_linked
+          modified_img
+        else
+          %(<a href="#{CGI.escapeHTML(src)}">#{modified_img}</a>)
+        end
+      end
+
+      document.output = output
+    end
+
+    # Check if a line is inside a code fence
+    #
+    # @param lines [Array<String>] all lines in the document
+    # @param line_idx [Integer] the current line index
+    # @return [Boolean] true if inside code fence
+    def self.in_code_fence?(lines, line_idx)
+      # Check for fenced code blocks (backticks or tildes)
+      fence_count = 0
+      (0...line_idx).each do |i|
+        # Match both backtick and tilde fences
+        fence_count += 1 if lines[i] =~ /^(`{3,}|~{3,})/
+      end
+      # Odd count means we're inside a fence
+      return true if fence_count.odd?
+
+      # Check for indented code blocks
+      # A line is in an indented code block if there's a contiguous run
+      # of indented lines (4+ spaces or tab) leading up to it
+      return false if line_idx.zero?
+
+      # Check if current line and previous lines are indented
+      idx = line_idx
+      while idx > 0
+        line = lines[idx]
+        # If line starts with 4+ spaces or tab, it's indented code
+        break unless line =~ /^(    |\t)/
+
+        idx -= 1
+      end
+
+      # If we found a contiguous run of indented lines reaching current line
+      idx < line_idx
+    end
+
+    # Check if text position is inside inline code
+    #
+    # @param line [String] the line of text
+    # @param position [Integer] the position in the line
+    # @return [Boolean] true if inside inline code
+    def self.in_inline_code?(line, position)
+      # Count backticks before the position
+      backtick_count = 0
+      line[0...position].each_char do |char|
+        backtick_count += 1 if char == "`"
+      end
+      # Odd count means we're inside inline code
+      backtick_count.odd?
+    end
+  end
+end
+
+# Register Jekyll hooks
+Jekyll::Hooks.register :documents, :pre_render do |document|
+  JekyllHighlightCards::ImageSizingHooks.process_pre_render(document)
+end
+
+Jekyll::Hooks.register :documents, :post_render do |document|
+  JekyllHighlightCards::ImageSizingHooks.process_post_render(document)
+end

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Liquid tag for creating styled link card components
+  #
+  # Syntax:
+  #   {% linkcard URL [TITLE] [archive:ARCHIVE_URL] %}
+  #
+  # Parameters:
+  #   - URL (required): The URL to link to (can be Liquid expression)
+  #   - TITLE (optional): Title text to display (can be Liquid expression)
+  #   - archive:URL (optional): Explicit archive URL or "none" to opt out
+  #
+  # Examples:
+  #   {% linkcard https://example.com %}
+  #   {% linkcard https://example.com My Link Title %}
+  #   {% linkcard {{ page.url }} {{ page.title }} %}
+  #   {% linkcard https://example.com Title archive:none %}
+  class LinkcardTag < Liquid::Tag
+    include ArchiveHelper
+    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 linkcard tag
+    #
+    # @param context [Liquid::Context] the Liquid rendering context
+    # @return [String] rendered HTML
+    def render(context)
+      # Parse markup
+      parsed = split_markup(@markup)
+
+      # Resolve URL (required)
+      url = resolve_url(parsed[:url], context)
+      raise ArgumentError, "linkcard tag requires a URL" if url.nil? || url.empty?
+
+      # Resolve title (optional)
+      title = resolve_title(parsed[:title], context)
+
+      # Resolve archive (optional, may auto-lookup)
+      archive_url = resolve_archive(parsed[:archive], context, url)
+
+      # Build template variables
+      variables = build_template_variables(url, title, archive_url)
+
+      # Get site from context
+      site = context.registers[:site]
+
+      # Render template
+      render_template(site, "linkcard", variables)
+    end
+
+    private
+
+    # Parse the tag markup into URL, title, and archive components
+    #
+    # @param markup [String] the tag markup
+    # @return [Hash] parsed components
+    def split_markup(markup)
+      # 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 # Track nested Liquid expressions
+      escaped = false # Track if next character is escaped
+
+      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 > 0
+          in_liquid -= 1
+          current += char
+        # Track quote boundaries
+        elsif ['"', "'"].include?(char) && !in_quotes && in_liquid == 0
+          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 == 0
+          tokens << current unless current.empty?
+          current = ""
+        else
+          current += char
+        end
+      end
+      tokens << current unless current.empty?
+
+      # First token is URL, remaining tokens may be title or archive parameter
+      result = {
+        url: tokens.shift,
+        title: nil,
+        archive: nil
+      }
+
+      # Process remaining tokens
+      tokens.each do |token|
+        if token.start_with?("archive:")
+          result[:archive] = token.sub(/^archive:/, "")
+        else
+          # Accumulate title tokens
+          result[:title] = result[:title].nil? ? token : "#{result[:title]} #{token}"
+        end
+      end
+
+      result
+    end
+
+    # Resolve URL from token (may be Liquid expression or literal)
+    #
+    # @param token [String] the URL token
+    # @param context [Liquid::Context] the Liquid context
+    # @return [String] resolved URL
+    def resolve_url(token, context)
+      return nil if token.nil? || token.empty?
+
+      evaluate_expression(token, context, allow_nil: false)
+    end
+
+    # Resolve title from source (may be Liquid expression or literal)
+    #
+    # @param source [String, nil] the title source
+    # @param context [Liquid::Context] the Liquid context
+    # @return [String, nil] resolved title
+    def resolve_title(source, context)
+      return nil if source.nil? || source.empty?
+
+      evaluate_expression(source, context, allow_nil: true)
+    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
+    # @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 && source.downcase == "none"
+
+      # Check for explicit archive URL
+      return evaluate_expression(source, context, allow_nil: true) if source && !source.empty?
+
+      # Auto-lookup if enabled
+      return archive_url_for(url) if archive_enabled?
+
+      nil
+    end
+
+    # Build template variables hash for rendering
+    #
+    # @param url [String] the link URL
+    # @param title [String, nil] the title text
+    # @param archive_url [String, nil] the archive URL
+    # @return [Hash] template variables with raw and escaped versions
+    def build_template_variables(url, title, archive_url)
+      display_url = strip_protocol(url)
+
+      {
+        "url" => url,
+        "display_url" => display_url,
+        "title" => title,
+        "archive_url" => archive_url,
+        "escaped_url" => CGI.escapeHTML(url),
+        "escaped_display_url" => CGI.escapeHTML(display_url),
+        "escaped_title" => title ? CGI.escapeHTML(title) : nil,
+        "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("linkcard", JekyllHighlightCards::LinkcardTag)