jekyll-highlight-cards 0.3.1

data/README.md

@@ -0,0 +1,228 @@
+# jekyll-highlight-cards
+
+A Jekyll plugin providing styled card components for links and images with Internet Archive integration.
+
+## Features
+
+- **`{% linkcard %}`** - Styled link cards with optional titles and archive links
+- **`{% polaroid %}`** - Polaroid-style image cards with titles, links, and archive support
+- **Markdown Image Sizing** - Extended syntax for image dimensions: `![alt](image.jpg =300x200)`
+- **Internet Archive Integration** - Automatic lookup and archival for both tags
+- **Customizable** - Override HTML templates and CSS styles
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'jekyll-highlight-cards'
+```
+
+Add to your `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-highlight-cards
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+Add to your `main.scss` file:
+
+```scss
+@import "highlight-cards";
+```
+
+## Usage
+
+### Linkcard Tag
+
+Highlight links:
+
+![Linkcard visual example](docs/linkcard-example.jpg)
+
+```liquid
+{% linkcard https://example.com %}
+{% linkcard https://example.com My Cool Title %}
+{% linkcard https://example.com Title archive:none %}
+{% linkcard https://example.com archive:https://web.archive.org/... %}
+```
+
+**Parameters:**
+| Parameter        | Description                                                      |
+|------------------|------------------------------------------------------------------|
+| URL              | (required, first parameter)                                      |
+| Title            | (optional, everything after URL until `archive:`)                |
+| `archive:URL`    | Explicit archive URL                                             |
+| `archive:none`   | Disable archive lookup                                           |
+
+### Polaroid Tag
+
+Create polaroid-style image cards:
+
+![Polaroid visual example](docs/polaroid-example.jpg)
+
+```liquid
+{% polaroid /assets/image.jpg %}
+{% polaroid /assets/image.jpg size=300x200 %}
+{% polaroid /assets/image.jpg size=400x title="My Photo" %}
+{% polaroid /assets/image.jpg alt="Screen reader description" %}
+{% polaroid /assets/image.jpg alt="Alt text" title="Visible Title" %}
+{% polaroid /assets/image.jpg title="Photo" link="https://example.com" %}
+{% polaroid {{ page.image }} size=x400 title={{ page.title }} %}
+```
+
+**Parameters:**
+| Parameter          | Description                                                                                              |
+|--------------------|----------------------------------------------------------------------------------------------------------|
+| Image URL          | (required, first parameter)                                                                              |
+| `size=WxH`         | Image dimensions. Formats: `300x200`, `300x`, `x200`, `300`, `400pxx300px`                               |
+| `alt="..."`        | Alt text for image (for accessibility)                                                                   |
+| `title="..."`      | Title text displayed below image (also used as alt fallback)                                             |
+| `link="..."`       | Explicit URL to link to                                                                                  |
+| `archive="..."`    | Archive URL or `none` to disable                                                                         |
+
+**Image Alt Text:**
+The `alt` attribute priority: explicit `alt` parameter → `title` parameter → empty string.
+
+This allows you to:
+- Set accessible alt text without displaying a visible title
+- Use title as both visual label and screen reader description
+- Separate concerns: detailed alt for accessibility, brief title for display
+
+**Link Display:**
+- **No `link` parameter:** Image links to itself, no visible link text shown
+- **With `link` parameter:** Image and visible link text both point to the specified URL
+
+**Stacking:**
+
+By default, the Polaroids are displayed centered in their available space. Two Polaroids in a row will be [stacked vertically](docs/polaroid-stacked-example.jpg).
+
+If you want Polaroids to fill the available width [side-by-side](docs/polaroid-sidebyside-example.jpg), add the following to your `main.scss` file:
+
+```css
+.polaroid-container {
+  display: inline-block;
+  width: auto;
+}
+```
+
+### Markdown Image Sizing
+
+Add dimensions to Markdown images:
+
+```markdown
+![Alt text](image.jpg =300x200)
+![Alt text](image.jpg =400x)
+![Alt text](image.jpg =x300)
+![Alt text](image.jpg =400pxx300px)
+```
+
+Sized images are automatically wrapped in links to themselves.
+
+## Configuration
+
+### Internet Archive
+
+Enable automatic archive lookup:
+
+```bash
+export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1
+```
+
+Or in your shell config:
+
+```bash
+# In .bashrc, .zshrc, etc.
+export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1
+```
+
+### CSS Styles
+
+Import defaults and override specific properties:
+
+```scss
+@import "highlight-cards";
+
+.link-card {
+  border-color: red;  // Override
+}
+```
+
+The default style are structural only - they create the shapes but don't set colors, fonts, etc.
+The recommended approach is to use the default styles and then add aesthetics to the provided classes.
+
+### Template Customization
+
+If the provided HTML structure doesn't work for you, you can override templates by creating files in your Jekyll site:
+
+**Linkcard template:**
+- Create `_includes/highlight-cards/linkcard.html`
+
+**Polaroid template:**
+- Create `_includes/highlight-cards/polaroid.html`
+
+Templates receive these variables:
+
+**Linkcard variables:**
+- `url`, `display_url`, `title`, `archive_url`
+- `escaped_url`, `escaped_display_url`, `escaped_title`, `escaped_archive_url`
+
+**Polaroid variables:**
+- `image_url`, `link_url`, `title`, `link_display`, `archive_url`, `width`, `height`
+- `escaped_*` versions of all text fields
+
+See default templates in gem's `_includes/` directory for examples.
+
+## Examples
+
+### Blog post with link card
+
+```markdown
+---
+title: My Blog Post
+---
+
+Check out this cool site:
+
+{% linkcard https://jekyllrb.com Jekyll - Simple, blog-aware, static sites %}
+
+More content here...
+```
+
+### Gallery with polaroids
+
+```markdown
+---
+title: Photo Gallery
+photos:
+  - url: /assets/photo1.jpg
+    title: Sunset
+  - url: /assets/photo2.jpg
+    title: Mountains
+---
+
+{% for photo in page.photos %}
+  {% polaroid {{ photo.url }} size=300x300 title={{ photo.title }} %}
+{% endfor %}
+```
+
+### Sized images in Markdown
+
+```markdown
+Here's a large image:
+
+![My Photo](photo.jpg =800x600)
+
+And a smaller one:
+
+![Thumbnail](thumb.jpg =150x150)
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

data/_includes/highlight-cards/linkcard.html

@@ -0,0 +1,13 @@
+<blockquote class="link-card">
+  {% if title %}
+  <h1>{{ escaped_title }}</h1>
+  {% endif %}
+  <a href="{{ escaped_url }}" target="_blank" rel="noopener">{{ escaped_display_url }}</a>
+  {% if archive_url %}
+  <small class="link-card-archive">
+    (<a href="{{ escaped_archive_url }}" target="_blank" rel="noopener">archive</a>)
+  </small>
+  {% endif %}
+</blockquote>
+
+

data/_includes/highlight-cards/polaroid.html

@@ -0,0 +1,22 @@
+<div class="polaroid-container">
+  <div class="polaroid">
+    <a href="{{ escaped_link_url }}"{% unless link_url == image_url %} target="_blank" rel="noopener"{% endunless %}>
+      <img src="{{ escaped_image_url }}" alt="{% if alt %}{{ escaped_alt }}{% elsif title %}{{ escaped_title }}{% endif %}"{% if width %} width="{{ width }}"{% endif %}{% if height %} height="{{ height }}"{% endif %} class="polaroid-image">
+    </a>
+    <div class="polaroid-title">{{ escaped_title }}</div>
+    <div class="polaroid-link">
+      {% if link_display %}
+      <a href="{{ escaped_link_url }}" target="_blank" rel="noopener">{{ escaped_link_display }}</a>
+      {% else %}
+      &nbsp;
+      {% endif %}
+    </div>
+    <small class="polaroid-archive">
+      {% if archive_url %}
+      (<a href="{{ escaped_archive_url }}" target="_blank" rel="noopener">archive</a>)
+      {% else %}
+      &nbsp;
+      {% endif %}
+    </small>
+  </div>
+</div>

data/_sass/_highlight-cards.scss

@@ -0,0 +1,92 @@
+/*
+ * jekyll-highlight-cards Default Styles
+ *
+ * These styles provide a sensible default appearance for linkcard and polaroid tags.
+ * You can override these styles in your Jekyll site by:
+ * 1. Not importing this file (fully custom CSS)
+ * 2. Importing and overriding specific classes
+ * 3. Using higher specificity selectors
+ *
+ * To use these styles, add to your site's _config.yml or main SCSS:
+ *   @use "highlight-cards";
+ *
+ * All styles use low specificity for easy customization.
+ */
+
+/* ============================================================================
+   Linkcard Styles
+   ========================================================================= */
+
+.link-card {
+  padding: 1em 1.25em;
+  text-align: center;
+  position: relative;
+}
+
+.link-card-archive {
+  position: absolute;
+  right: 0.75rem;
+  bottom: 0.5rem;
+}
+
+/* ============================================================================
+   Polaroid Styles
+   ========================================================================= */
+
+
+.polaroid-container {
+  display: block;
+  width: 100%;
+  text-align: center;
+}
+
+.polaroid {
+  display: inline-block;
+  position: relative;
+  border: 1px solid #333;
+  padding: 10px 10px 25px 10px;
+  margin: 1em;
+  background-color: #fff;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.3);
+  text-align: center;
+  max-width: 100%;
+  transition: box-shadow 0.2s ease, transform 0.2s ease;
+
+  .polaroid-image {
+    display: block;
+    max-width: 100%;
+    border: 1px solid #333;
+    margin: 0 auto;
+  }
+
+  .polaroid-title {
+    margin-top: 5px;
+    padding: 0 10px;
+  }
+
+  .polaroid-link {
+    margin-top: 5px;
+    padding: 0 10px;
+    word-break: break-all;
+  }
+
+  .polaroid-archive {
+    position: absolute;
+    right: 0.75rem;
+    bottom: 0.5rem;
+  }
+}
+
+/* ============================================================================
+   Print Styles
+   ========================================================================= */
+
+@media print {
+  .link-card,
+  .polaroid {
+    box-shadow: none;
+    border: 1px solid #333;
+    page-break-inside: avoid;
+  }
+}
+

data/jekyll-highlight-cards.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/jekyll-highlight-cards/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-highlight-cards"
+  spec.version       = JekyllHighlightCards::VERSION
+  spec.authors       = ["Texarkanine"]
+  spec.email         = ["texarkanine@protonmail.com"]
+
+  spec.summary       = "Jekyll plugin providing linkcard and polaroid Liquid tags with archive integration"
+  spec.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."
+  spec.homepage      = "https://github.com/texarkanine/jekyll-highlight-cards"
+  spec.license       = "AGPL-3.0-or-later"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|planning|examples)/})
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "jekyll", ">= 4.0", "< 5.0"
+  spec.add_dependency "liquid", ">= 4.0", "< 5.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Internet Archive integration for automatic URL archival
+  #
+  # Provides methods for looking up existing archives and submitting
+  # URLs to the Internet Archive's Wayback Machine. Results are cached
+  # per-site-build to avoid redundant API calls.
+  #
+  # @example Enable archiving
+  #   export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1
+  #
+  # @example Enable auto-submission
+  #   export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_SAVE=1
+  module ArchiveHelper
+    # Shared cache for archive URLs across all tag instances
+    @archive_cache = {}
+
+    class << self
+      attr_accessor :archive_cache
+    end
+
+    # Get archive URL for a given URL, with caching and optional submission
+    #
+    # @param url [String] the original URL to archive
+    # @return [String, nil] the archive URL, or nil if not found
+    def archive_url_for(url)
+      ArchiveHelper.archive_cache[url] ||= begin
+        log_info("Looking up archive for #{url}")
+        archive_url = lookup_archive(url)
+        log_info("Archive URL: #{archive_url || ""}")
+
+        if archive_save_enabled?
+          log_info("Submitting to SavePageNow: #{url}")
+          archive_url = submit_archive(url) || archive_url
+          log_info("SavePageNow archived #{url} -> #{archive_url}")
+        end
+
+        archive_url.to_s.empty? ? nil : archive_url
+      end
+    rescue StandardError => e
+      log_debug("Archive lookup failed for #{url}: #{e.message}")
+      nil
+    end
+
+    # Check if archiving is enabled via environment variables
+    #
+    # @return [Boolean] true if archiving is enabled
+    def archive_enabled?
+      ENV["JEKYLL_HIGHLIGHT_CARDS_ARCHIVE"] == "1" || archive_save_enabled?
+    end
+
+    # Check if SavePageNow submission is enabled
+    #
+    # @return [Boolean] true if submission is enabled
+    def archive_save_enabled?
+      ENV["JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_SAVE"] == "1"
+    end
+
+    # Get User-Agent string for archive HTTP requests
+    #
+    # @return [String] User-Agent header value
+    def archive_user_agent
+      ENV["JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_UA"] ||
+        "jekyll:highlight-cards (+#{ENV.fetch("JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_CONTACT", "mailto:unknown")})"
+    end
+
+    private
+
+    # Look up the latest archived snapshot for a URL via Internet Archive CDX API
+    #
+    # @param url [String] the URL to look up
+    # @return [String, nil] the archive URL if found, nil otherwise
+    def lookup_archive(url)
+      log_debug("lookup_archive(#{url})")
+
+      encoded_url = URI.encode_www_form_component(url)
+      cdx_url_str = "https://web.archive.org/cdx/search/cdx?url=#{encoded_url}&output=json&filter=statuscode:200&limit=-1&fl=timestamp,original"
+      cdx_url = URI.parse(cdx_url_str)
+
+      log_debug("CDX lookup URL: #{cdx_url_str}")
+
+      response = Net::HTTP.start(
+        cdx_url.host,
+        cdx_url.port,
+        use_ssl: cdx_url.scheme == "https",
+        open_timeout: 10,
+        read_timeout: 30
+      ) do |http|
+        http.request(Net::HTTP::Get.new(cdx_url.request_uri))
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        log_debug("CDX lookup failed: #{response.code} #{response.message}")
+        return nil
+      end
+
+      log_debug("CDX lookup found archived page...")
+      rows = JSON.parse(response.body)
+
+      # First row is header, so we need at least 2 rows
+      return nil if rows.length <= 1
+
+      latest = rows.last
+      timestamp = latest[0]
+      archive_url = "https://web.archive.org/web/#{timestamp}/#{url}"
+
+      log_debug("CDX lookup found archived page: #{archive_url}")
+      archive_url
+    rescue StandardError => e
+      log_debug("CDX lookup error for #{url}: #{e.message}")
+      nil
+    end
+
+    # Submit a URL to Internet Archive SavePageNow service
+    #
+    # @param url [String] the URL to submit for archiving
+    # @return [String, nil] the archive URL if successful, nil otherwise
+    def submit_archive(url)
+      log_debug("submit_archive(#{url})")
+
+      encoded_url = URI.encode_www_form_component(url)
+      save_url = URI.parse("https://web.archive.org/save/#{encoded_url}")
+
+      response = Net::HTTP.start(
+        save_url.host,
+        save_url.port,
+        use_ssl: save_url.scheme == "https",
+        open_timeout: 10,
+        read_timeout: 30
+      ) do |http|
+        req = Net::HTTP::Get.new(save_url.request_uri, { "User-Agent" => archive_user_agent })
+        http.request(req)
+      end
+
+      location = response["content-location"]
+
+      if location && !location.empty?
+        archive_url = "https://web.archive.org#{location}"
+        log_info("SavePageNow archived #{url} -> #{archive_url}")
+        archive_url
+      else
+        log_debug("Archive submission returned no location for #{url}")
+        nil
+      end
+    rescue StandardError => e
+      log_debug("Archive submission error for #{url}: #{e.message}")
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module JekyllHighlightCards
+  # Parse dimension specifications in "WxH" format
+  #
+  # Supports multiple formats for specifying image dimensions:
+  # - `WIDTHxHEIGHT`: Both dimensions (e.g., "300x200")
+  # - `WIDTHx`: Width only (e.g., "300x")
+  # - `xHEIGHT`: Height only (e.g., "x200")
+  # - `WIDTH`: Width only shorthand (e.g., "300")
+  # - Units: Supports px, em, %, etc. (e.g., "400pxx300px")
+  #
+  # @example
+  #   include DimensionParser
+  #   width, height = parse_dimensions("300x200")  #=> ["300", "200"]
+  module DimensionParser
+    # Parse dimension string into width and height components
+    #
+    # @param dim_str [String] dimension string (e.g., "300x200", "300x", "x200", "300")
+    # @return [Array<String, nil>] array of [width, height] where nil indicates unspecified
+    #
+    # @example
+    #   parse_dimensions("300x200")  #=> ["300", "200"]
+    #   parse_dimensions("300x")     #=> ["300", nil]
+    #   parse_dimensions("x200")     #=> [nil, "200"]
+    #   parse_dimensions("300")      #=> ["300", nil]
+    #   parse_dimensions("400px")    #=> ["400px", nil]
+    def parse_dimensions(dim_str)
+      return [nil, nil] if dim_str.nil? || dim_str.empty?
+
+      # Determine the separator:
+      # - If "xx" is present, the SECOND 'x' is the separator (first 'x' is part of the dimension)
+      #   Example: "400pxx300px" → width="400px", height="300px"
+      # - Otherwise, check if there's an 'x' that's a separator (not part of a unit like "px")
+      #   An 'x' is a separator if it's at the end, followed by a digit, or at the start
+      if dim_str.include?("xx")
+        # Find the position of "xx"
+        idx = dim_str.index("xx")
+        # Split at the second 'x' (include first 'x' in width, skip both 'x's for height)
+        width = dim_str[0..idx].empty? ? nil : dim_str[0..idx]
+        height = dim_str[(idx + 2)..]
+        height = nil if height.nil? || height.empty?
+        [width, height]
+      elsif dim_str =~ /x\d/ || dim_str =~ /(?<![a-z])x$/i || dim_str.start_with?("x")
+        # Single 'x' separator in one of these cases:
+        # 1. Followed by a digit: "300x200", "10emx20em"
+        # 2. At end but NOT preceded by a letter: "300x"
+        # 3. At start: "x200"
+        # This matches "300x", "300x200", "x200", "10emx20em", but NOT "400px"
+        parts = dim_str.split("x", 2)
+        width = parts[0].empty? ? nil : parts[0]
+        height = parts[1].nil? || parts[1].empty? ? nil : parts[1]
+        [width, height]
+      else
+        # No separator found - treat as width only
+        [dim_str, nil]
+      end
+    end
+
+    module_function :parse_dimensions
+  end
+end