jekyll-og-image 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7498d6e0fca6a90a0c70efb97a4514293b396e20af0900cfa5c734d88ed2cbf0
-  data.tar.gz: fea25610cb98a2b2954440c796800087a5379142b796c503ac7822034950fb17
+  metadata.gz: 5a95a1847180a7d4565e7e951467ff2293fb88e7182b08a58f362aee77f4a1d9
+  data.tar.gz: f11ab1b7b52feec3c6052b46884da96dd1973fc863293d74ac36ac7c22142bd4
 SHA512:
-  metadata.gz: b6177ac6d1493b968a2eb2d33a13f84429d90be409839d2e08407a20e8b4296a5e9a50dc38d630f867ad113a931efb6fd9d6302d4a5732a167b82aec0e08dfa2
-  data.tar.gz: 3661a2e8dcb52b274d73d2ef713bc6fa365b9a3102bc652098bf7759e0babe3b6c253133fafdcc3c7c0ef6d57272da47c78d1d937ac111efa1abff4231d25860
+  metadata.gz: e49a4a7fb8884c6f3898dae7ec54b8185809d1211544d16ad8cbe8b70a60aa4be81aff27a60f182873b6e62048f2fb9bc402dd92c1f4b3d8f8b1b8ceda411ec3
+  data.tar.gz: 5879cfbe269524ebf28e08dfd68f79d0e1782471b09f7dd74390133a7c62930a846957ac42e2351414f0a7c3d99738acc571905dc2449034771874fd5a6c2d6f

data/README.md

@@ -1,16 +1,29 @@
-# Jekyll OG Image
+<p align="center">
+  <img src="assets/icon.svg" alt="Jekyll OG Image" width="128" height="128">
+</p>
 
-A Jekyll plugin to automatically generate open graph images for posts.
+<h1 align="center">Jekyll OG Image</h1>
 
-[![Gem Version](https://badge.fury.io/rb/jekyll-og-image.svg)](https://badge.fury.io/rb/jekyll-og-image)
-[![Lint](https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/lint.yml)
-[![Tests](https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/tests.yml)
+<p align="center">
+  A Jekyll plugin to automatically generate open graph images for posts.
+</p>
+
+<p align="center">
+  <a href="https://badge.fury.io/rb/jekyll-og-image"><img src="https://badge.fury.io/rb/jekyll-og-image.svg" alt="Gem Version"></a>
+  <a href="https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/lint.yml"><img src="https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/lint.yml/badge.svg?branch=main" alt="Lint"></a>
+  <a href="https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/tests.yml"><img src="https://github.com/igor-alexandrov/jekyll-og-image/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests"></a>
+</p>
+
+<p align="center">
+  <img src="examples/1.png" alt="Example open graph image" width="600">
+</p>
 
 ## Installation
 
 Add this line to your site's Gemfile:
 
 ```ruby
+  gem 'jekyll-seo-tag'
   gem 'jekyll-og-image'
 ```
 
@@ -22,13 +35,11 @@ plugins:
   - jekyll-og-image
 ```
 
-This plugin requires `libvips` to be installed. If you are using GitHub Pages to host your Jekyll site, don't forget to install `libvips` before running `jekyll build`. See the example below.
+The plugin requires Ruby 3.2 or newer and [libvips](https://www.libvips.org/install.html). If you are using GitHub Pages to host your Jekyll site, don't forget to install `libvips` before running `jekyll build`. See the example below.
 
 ``` yaml
 jobs:
   build:
-    needs:
-      - lint
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -40,16 +51,6 @@ jobs:
           ruby-version: .ruby-version
           bundler-cache: true
 
-      - name: Set Node.js 20.x
-        uses: actions/setup-node@v3
-        with:
-          node-version: 20.x
-
-      - name: Run install
-        uses: borales/actions-yarn@v4
-        with:
-          cmd: install
-
       - name: Update apt
         env:
           DEBIAN_FRONTEND: noninteractive
@@ -65,19 +66,28 @@ jobs:
         uses: actions/configure-pages@v5
 
       - name: Build with Jekyll
-        run: ./bin/jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
         env:
           JEKYLL_ENV: production
 
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
         uses: actions/upload-pages-artifact@v3
-
 ```
 
 ## Usage
 
-Jekyll OG Image works together with [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) plugin. It automatically generates open graph images for posts and inserts them into the posts metadata.
+Jekyll OG Image works together with the [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) plugin. It generates open graph images for posts and sets them as the `image` in each post's front matter, which jekyll-seo-tag turns into `og:image` and `twitter:image` meta tags. jekyll-seo-tag isn't installed automatically, so add it to your Gemfile yourself, as shown above.
+
+### Regenerating images
+
+An image is regenerated when anything that affects it changes: the document's title or metadata, the plugin configuration (site-wide or in front matter), the logo or background image files, or the plugin version. Otherwise the existing image is kept, so builds stay fast and `jekyll serve` doesn't rewrite unchanged files.
+
+To track this, the plugin keeps a fingerprint of each image in `.jekyll-og-image.json` inside `output_dir`. Jekyll doesn't publish it. If you commit generated images to your repository, commit this file too; without it, every image is regenerated once.
+
+### Upgrading from 2.x
+
+Images used to be named after the document's title or slug, which let two documents with the same title share one image. They are now named after the source file (see `output_dir` below), so every image gets a new path and URL on the first build after upgrading. The old images are left in place. Delete them from `output_dir` if you committed them to your repository.
 
 ## Configuration
 
@@ -85,11 +95,15 @@ The plugin can be configured in the `_config.yml` file or in the post's front ma
 
 The following configuration options are available:
 
+Colors are hex values in `"#RRGGBB"` or `"#RGB"` form. Quote them in YAML, because an unquoted `#` starts a comment.
+
+Paths to images (`image.path`, `canvas.background_image`) are relative to the site's source directory. If a file doesn't exist, the plugin logs a warning and generates the image without it.
+
 * `collections` - An array specifying which types of collections to generate images for. Supports `"posts"`, `"pages"`, and the names of any custom collections. Default: `["posts"]`
 
-* `output_dir` – The directory where the generated images will be saved. Images will be placed in subdirectories named after their collection type (e.g., `assets/images/og/posts`, `assets/images/og/pages`). Default: `assets/images/og`
+* `output_dir` – The directory where the generated images will be saved. Images are placed in a subdirectory named after their collection type and named after their source file, e.g. `_posts/2024-02-15-hello.md` → `assets/images/og/posts/2024-02-15-hello.png` and `blog/index.md` → `assets/images/og/pages/blog/index.png`. Default: `assets/images/og`
 
-* `force` – If set to `true`, the plugin will generate an image for every document, even if the document already has an image. Default: `false`
+* `force` – If set to `true`, every image is regenerated on each build, even when it is up to date. Rarely needed, since images are regenerated automatically when they change (see [Regenerating images](#regenerating-images)). Under `jekyll serve`, it applies to the first build only. Default: `false`
 * `verbose`  – If set to `true`, the plugin will output additional information about the image generation process. Default: `false`
 
 * `skip_drafts` – If set to `true`, the plugin will skip post drafts when generating images. Default: `true`
@@ -97,10 +111,10 @@ The following configuration options are available:
 * `canvas` – The canvas configuration options:
   * `background_color` – The background color of the canvas. Default: `#FFFFFF`
   * `background_image` – The background image of the canvas. Default: `nil`
-  * `width` – The width of the generated image in pixels. Default: `1200`
+  * `width` – The width of the generated image in pixels. The layout is designed for a 1200px-wide canvas and scales with this width: margins, text sizes, and the logo and border sizes below are all given for 1200px. Default: `1200`
   * `height` – The height of the generated image in pixels. Default: `600`
 
-* `header` – The header configuration options:
+* `header` – The header configuration options. A title too long for the space above the metadata line is shrunk to fit.
   * `font_family` – The font family of the header text. Default: `Helvetica, Bold`
   * `color` – The color of the header text. Default: `#2f313d`
   * `prefix` – Text to prepend to the title. Default: `""`
@@ -111,7 +125,7 @@ The following configuration options are available:
   * `color` – The color of the content text. Default: `#535358`
 
 * `border_bottom` – The border bottom configuration options:
-  * `width` – The width of the border bottom. Default: `20`
+  * `width` – The width of the border bottom. Default: `0`
   * `fill` – The array of colors to fill the border bottom. Default: `["#000000"]`
 
 * `domain` – The domain name to use in the image. Default: `nil`
@@ -122,7 +136,7 @@ The following configuration options are available:
   * `height` – The height of the logo in pixels. Default: `150`
   * `radius` – The radius for rounded corners on the logo. Default: `50`
   * `position` – The position of the logo as `{x, y}` coordinates. Default: `{x: 80, y: 100}`
-  * `gravity` – The gravity anchor for logo positioning (nw, n, ne, w, e, sw, s, se). Default: `ne`
+  * `gravity` – The gravity anchor for logo positioning (nw, ne, sw, se). Default: `ne`
 
 * `metadata` – The metadata configuration options:
   * `fields` – Array of metadata fields to display. Available options: `"date"`, `"tags"`, or any custom front matter field. Default: `["date", "tags"]`

data/assets/icon.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#3a3d4c"/>
+      <stop offset="1" stop-color="#1f2029"/>
+    </linearGradient>
+    <linearGradient id="logo" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#EDA895"/>
+      <stop offset="1" stop-color="#D51F06"/>
+    </linearGradient>
+    <clipPath id="card">
+      <rect x="48" y="148" width="416" height="248" rx="24"/>
+    </clipPath>
+  </defs>
+
+  <rect width="512" height="512" rx="112" fill="url(#bg)"/>
+
+  <rect x="96" y="108" width="320" height="248" rx="24" fill="#ffffff" opacity="0.18"/>
+  <rect x="72" y="128" width="368" height="248" rx="24" fill="#ffffff" opacity="0.36"/>
+
+  <g clip-path="url(#card)">
+    <rect x="48" y="148" width="416" height="248" fill="#ffffff"/>
+
+    <rect x="84" y="184" width="224" height="30" rx="15" fill="#2f313d"/>
+    <rect x="84" y="226" width="148" height="30" rx="15" fill="#2f313d"/>
+
+    <rect x="360" y="184" width="68" height="68" rx="18" fill="url(#logo)"/>
+
+    <rect x="84" y="290" width="112" height="12" rx="6" fill="#a4a4ab"/>
+    <rect x="84" y="316" width="168" height="12" rx="6" fill="#a4a4ab"/>
+    <rect x="360" y="290" width="68" height="12" rx="6" fill="#a4a4ab"/>
+
+    <rect x="48"    y="364" width="83.2" height="32" fill="#820C02"/>
+    <rect x="131.2" y="364" width="83.2" height="32" fill="#A91401"/>
+    <rect x="214.4" y="364" width="83.2" height="32" fill="#D51F06"/>
+    <rect x="297.6" y="364" width="83.2" height="32" fill="#DE3F24"/>
+    <rect x="380.8" y="364" width="83.2" height="32" fill="#EDA895"/>
+  </g>
+</svg>

data/lib/jekyll_og_image/configuration.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# require "anyway_config"
-
 class JekyllOgImage::Configuration
   Canvas = Data.define(:background_color, :background_image, :width, :height) do
     def initialize(background_color: "#FFFFFF", background_image: nil, width: 1200, height: 600)
@@ -23,14 +21,16 @@ class JekyllOgImage::Configuration
 
   Border = Data.define(:width, :fill) do
     def initialize(width: 0, fill: nil)
-      fill.is_a?(Array) ? fill : [ fill ]
-      super(width: width, fill: fill)
+      super(width: width, fill: Array(fill || "#000000"))
     end
   end
 
   Image = Data.define(:path, :width, :height, :radius, :position, :gravity) do
-    def initialize(path: nil, width: 150, height: 150, radius: 50, position: { x: 80, y: 100 }, gravity: :ne)
-      super
+    def initialize(path: nil, width: 150, height: 150, radius: 50, position: {}, gravity: :ne)
+      # Values read from YAML have string keys and string gravity
+      position = { x: 80, y: 100 }.merge(position.transform_keys(&:to_sym))
+
+      super(path: path, width: width, height: height, radius: radius, position: position, gravity: gravity.to_sym)
     end
   end
 
@@ -44,7 +44,7 @@ class JekyllOgImage::Configuration
     @raw_config = raw_config
   end
 
-  def merge!(other)
+  def merge(other)
     config = Jekyll::Utils.deep_merge_hashes(
       @raw_config,
       other.to_h
@@ -86,26 +86,22 @@ class JekyllOgImage::Configuration
   end
 
   def canvas
-    @raw_config["canvas"] ? Canvas.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["canvas"])) : Canvas.new
+    build_section(Canvas, "canvas")
   end
 
   def header
-    @raw_config["header"] ? Header.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["header"])) : Header.new
+    build_section(Header, "header")
   end
 
   def content
-    @raw_config["content"] ? Content.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["content"])) : Content.new
+    build_section(Content, "content")
   end
 
   def image
-    if @raw_config["image"].is_a?(String)
-      # Legacy support: if image is just a string, convert it to the new format
-      Image.new(path: @raw_config["image"])
-    elsif @raw_config["image"]
-      Image.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["image"]))
-    else
-      Image.new
-    end
+    # Legacy support: if image is just a string, convert it to the new format
+    return Image.new(path: @raw_config["image"]) if @raw_config["image"].is_a?(String)
+
+    build_section(Image, "image")
   end
 
   def domain
@@ -113,15 +109,31 @@ class JekyllOgImage::Configuration
   end
 
   def border_bottom
-    @raw_config["border_bottom"] ? Border.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["border_bottom"])) : nil
+    build_section(Border, "border_bottom") if @raw_config["border_bottom"]
   end
 
-  def margin_bottom
-    80 + (border_bottom&.width || 0)
+  def metadata
+    build_section(Metadata, "metadata")
   end
 
+  private
 
-  def metadata
-    @raw_config["metadata"] ? Metadata.new(**Jekyll::Utils.symbolize_hash_keys(@raw_config["metadata"])) : Metadata.new
+  def build_section(klass, name)
+    value = @raw_config[name]
+    return klass.new unless value
+
+    unless value.is_a?(Hash)
+      raise Jekyll::Errors::InvalidConfigurationError, "og_image.#{name} must be a set of options, got #{value.inspect}"
+    end
+
+    options = Jekyll::Utils.symbolize_hash_keys(value)
+    unknown = options.keys - klass.members
+
+    if unknown.any?
+      raise Jekyll::Errors::InvalidConfigurationError,
+        "Unknown og_image.#{name} option: #{unknown.join(", ")}. Valid options: #{klass.members.join(", ")}"
+    end
+
+    klass.new(**options)
   end
 end

data/lib/jekyll_og_image/element/base.rb

@@ -5,14 +5,22 @@ class JekyllOgImage::Element::Base
 
   private
 
+  VALID_GRAVITY.each do |gravity|
+    define_method("gravity_#{gravity}?") do
+      @gravity == gravity
+    end
+  end
+
   def hex_to_rgb(input)
     case input
-    when String
-      input.match(/#(..)(..)(..)/)[1..3].map(&:hex)
     when Array
       input
+    when /\A#\h{3}\z/
+      input[1..].chars.map { |digit| (digit * 2).hex }
+    when /\A#\h{6}\z/
+      input[1..].scan(/\h\h/).map(&:hex)
     else
-      raise ArgumentError, "Unknown input #{input.inspect}"
+      raise ArgumentError, "Invalid color #{input.inspect}, expected a hex color like \"#FFFFFF\" or \"#FFF\""
     end
   end
 
@@ -31,18 +39,9 @@ class JekyllOgImage::Element::Base
   end
 
   def composite_with_gravity(canvas, overlay, x, y)
-    if gravity_nw?
-      canvas.composite(overlay, :over, x: [ x ], y: [ y ]).flatten
-    elsif gravity_ne?
-      x = canvas.width - overlay.width - x
-      canvas.composite(overlay, :over, x: [ x ], y: [ y ]).flatten
-    elsif gravity_sw?
-      y = canvas.height - overlay.height - y
-      canvas.composite(overlay, :over, x: [ x ], y: [ y ]).flatten
-    elsif gravity_se?
-      x = canvas.width - overlay.width - x
-      y = canvas.height - overlay.height - y
-      canvas.composite(overlay, :over, x: [ x ], y: [ y ]).flatten
-    end
+    x = canvas.width - overlay.width - x if gravity_ne? || gravity_se?
+    y = canvas.height - overlay.height - y if gravity_sw? || gravity_se?
+
+    canvas.composite(overlay, :over, x: [ x ], y: [ y ]).flatten
   end
 end

data/lib/jekyll_og_image/element/border.rb

@@ -7,7 +7,7 @@ class JekyllOgImage::Element::Border < JekyllOgImage::Element::Base
   def initialize(size, position: :bottom, fill: "#000000")
     @size = size
     @position = position
-    @fill = fill
+    @fill = Array(fill)
 
     validate_position!
   end
@@ -15,14 +15,11 @@ class JekyllOgImage::Element::Border < JekyllOgImage::Element::Base
   def apply_to(canvas, &block)
     border = Vips::Image.black(*dimensions(canvas))
 
-    parts(canvas).each.with_index do |part, index|
+    parts(canvas).each do |part|
       image = Vips::Image.black(part.width, part.height).ifthenelse([ 0, 0, 0 ], part.rgb)
+      x, y = vertical? ? [ 0, part.offset ] : [ part.offset, 0 ]
 
-      if vertical?
-        border = border.composite(image, :over, x: [ 0 ], y: [ part.offset ]).flatten
-      else
-        border = border.composite(image, :over, x: [ part.offset ], y: [ 0 ]).flatten
-      end
+      border = border.composite(image, :over, x: [ x ], y: [ y ]).flatten
     end
 
     result = block.call(canvas, border) if block_given?
@@ -40,10 +37,6 @@ class JekyllOgImage::Element::Border < JekyllOgImage::Element::Base
 
   private
 
-  def hex_to_rgb(hex)
-    hex.match(/#(..)(..)(..)/)[1..3].map { |x| x.hex }
-  end
-
   def dimensions(canvas)
     if vertical?
       [ @size, canvas.height ]
@@ -53,21 +46,15 @@ class JekyllOgImage::Element::Border < JekyllOgImage::Element::Base
   end
 
   def parts(canvas)
-    if @fill.is_a?(Array)
-      width, height = vertical? ? [ @size, (canvas.height / @fill.size) ] : [ (canvas.width / @fill.size), @size ]
-
-      @fill.map.with_index do |item, index|
-        Part.new(
-          rgb: hex_to_rgb(item),
-          width: width,
-          height: height,
-          offset: index * (vertical? ? height : width)
-        )
-      end
-    else
-      length = vertical? ? canvas.height : canvas.width
+    length = vertical? ? canvas.height : canvas.width
 
-      [ Part.new(rgb: hex_to_rgb(@fill), length: length, offset: 0) ]
+    @fill.map.with_index do |color, index|
+      # Stripe edges are rounded down, so the last stripe absorbs any remainder
+      from = length * index / @fill.size
+      to = length * (index + 1) / @fill.size
+      width, height = vertical? ? [ @size, to - from ] : [ to - from, @size ]
+
+      Part.new(rgb: hex_to_rgb(color), width: width, height: height, offset: from)
     end
   end
 
@@ -75,10 +62,6 @@ class JekyllOgImage::Element::Border < JekyllOgImage::Element::Base
     @position == :left || @position == :right
   end
 
-  def horizontal?
-    @position == :top || @position == :bottom
-  end
-
   def validate_position!
     unless %i[left right top bottom].include?(@position)
       raise ArgumentError, "Invalid position: #{@position.inspect}"

data/lib/jekyll_og_image/element/canvas.rb

@@ -14,8 +14,6 @@ class JekyllOgImage::Element::Canvas < JekyllOgImage::Element::Base
 
       @canvas = @canvas.composite(overlay, :over, x: [ 0 ], y: [ 0 ]).flatten
     end
-
-    @canvas
   end
 
   def image(source, **opts, &block)

data/lib/jekyll_og_image/element/image.rb

@@ -13,13 +13,19 @@ class JekyllOgImage::Element::Image < JekyllOgImage::Element::Base
 
   def apply_to(canvas, &block)
     image = Vips::Image.new_from_buffer(@source, "")
-    image = round_corners(image) if @radius
+
+    if image.bands != canvas.bands
+      image = image.flatten
+    end
 
     if @width && @height
       ratio = calculate_ratio(image, @width, @height, :min)
       image = image.resize(ratio)
     end
 
+    # Rounded after resizing, so the radius is in output pixels whatever the source size
+    image = round_corners(image) if @radius
+
     result = block.call(canvas, image) if block_given?
 
     x, y = result ? [ result.fetch(:x, 0), result.fetch(:y, 0) ] : [ 0, 0 ]
@@ -29,12 +35,6 @@ class JekyllOgImage::Element::Image < JekyllOgImage::Element::Base
 
   private
 
-  VALID_GRAVITY.each do |gravity|
-    define_method("gravity_#{gravity}?") do
-      @gravity == gravity
-    end
-  end
-
   def round_corners(image)
     mask = %(
       <svg viewBox="0 0 #{image.width} #{image.height}">

data/lib/jekyll_og_image/element/text.rb

@@ -1,10 +1,18 @@
 # frozen_string_literal: true
 
 class JekyllOgImage::Element::Text < JekyllOgImage::Element::Base
-  def initialize(message, gravity: :nw, width: nil, dpi: nil, color: "#000000", font: nil)
+  MARKUP_ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;" }.freeze
+
+  # Vips::Image.text parses its input as Pango markup, so plain text has to be escaped
+  def self.escape_markup(message)
+    message.to_s.gsub(/[&<>]/, MARKUP_ESCAPES)
+  end
+
+  def initialize(message, gravity: :nw, width: nil, height: nil, dpi: nil, color: "#000000", font: nil)
     @message = message
     @gravity = gravity
     @width = width
+    @height = height
     @dpi = dpi
     @color = color
     @font = font
@@ -22,7 +30,12 @@ class JekyllOgImage::Element::Text < JekyllOgImage::Element::Base
 
     params[:wrap] = :word if wrap_supported?
 
-    text = Vips::Image.text(@message, **params)
+    text = Vips::Image.text(self.class.escape_markup(@message), **params)
+
+    # Too tall: given a width and height instead of a dpi, libvips picks the largest dpi that fits
+    if @height && text.height > @height && height_supported?
+      text = Vips::Image.text(self.class.escape_markup(@message), **params.except(:dpi), height: @height)
+    end
 
     text = text
       .new_from_image(hex_to_rgb(@color))
@@ -38,10 +51,9 @@ class JekyllOgImage::Element::Text < JekyllOgImage::Element::Base
 
   private
 
-  VALID_GRAVITY.each do |gravity|
-    define_method("gravity_#{gravity}?") do
-      @gravity == gravity
-    end
+  def height_supported?
+    # Vips::Image.text fits text to a height since vips 8.8.0
+    Vips.at_least_libvips?(8, 8)
   end
 
   def wrap_supported?

data/lib/jekyll_og_image/generator.rb

@@ -1,60 +1,66 @@
 # frozen_string_literal: true
 
+require "digest"
+
 class JekyllOgImage::Generator < Jekyll::Generator
   safe true
 
   def generate(site)
     config = JekyllOgImage.config
+    @missing_files = Set.new
+    @file_digests = {}
+    manifest = JekyllOgImage::Manifest.new(File.join(site.source, config.output_dir))
+
+    # `jekyll serve` reuses this generator for every rebuild. Forcing only the first
+    # build stops rewritten images from triggering the watcher in an endless loop.
+    @first_build = !@built
+    @built = true
 
     config.collections.each do |type|
-      process_collection(site, type, config)
+      process_collection(site, type, config, manifest)
     end
+
+    manifest.save
   end
 
   private
 
-  def process_collection(site, type, config)
+  def process_collection(site, type, config, manifest)
     Jekyll.logger.info "Jekyll Og Image:", "Processing type: #{type}" if config.verbose?
 
-    items = get_items_for_collection(site, type)
-    return if items.empty?
-
-    base_output_dir = File.join(config.output_dir, type)
-    absolute_output_dir = File.join(site.config["source"], base_output_dir)
-    FileUtils.mkdir_p absolute_output_dir
-
-    items.each do |item|
+    get_items_for_collection(site, type).each do |item|
       if item.respond_to?(:draft?) && item.draft? && config.skip_drafts?
         Jekyll.logger.info "Jekyll Og Image:", "Skipping draft: #{item.data['title']}" if config.verbose?
         next
       end
 
-      fallback_basename = if item.respond_to?(:basename_without_ext)
-                            item.basename_without_ext
-                            # rubocop:disable Layout/ElseAlignment # Disabled due to RuboCop error in v3.3.0
-                          else
-                            # rubocop:enable Layout/ElseAlignment
-                            File.basename(item.name, File.extname(item.name))
-      end
+      item_config = config.merge(item.data["og_image"] || {})
+      next unless item_config.enabled?
 
-      slug = item.data["slug"] || Jekyll::Utils.slugify(item.data["title"] || fallback_basename)
-      image_filename = "#{slug}.png"
-      absolute_image_path = File.join(absolute_output_dir, image_filename)
-      relative_image_path = File.join("/", base_output_dir, image_filename) # Use leading slash for URL
+      image_path = File.join(type, "#{image_basename(item)}.png")
+      site_image_path = File.join(config.output_dir, image_path)
+      absolute_image_path = File.join(site.source, site_image_path)
+      digest = image_digest(site, item, item_config)
 
-      if !File.exist?(absolute_image_path) || config.force?
+      force = @first_build && item_config.force?
+
+      if force || !File.exist?(absolute_image_path) || !manifest.fresh?(image_path, digest)
         Jekyll.logger.info "Jekyll Og Image:", "Generating image #{absolute_image_path}" if config.verbose?
-        generate_image_for_document(site, item, absolute_image_path, config)
+        FileUtils.mkdir_p(File.dirname(absolute_image_path))
+        generate_image_for_document(site, item, absolute_image_path, item_config)
       else
-        Jekyll.logger.info "Jekyll Og Image:", "Skipping image generation for #{relative_image_path} as it already exists." if config.verbose?
+        Jekyll.logger.info "Jekyll Og Image:", "Skipping #{site_image_path}, it is up to date" if config.verbose?
       end
 
-      register_static_file(site, base_output_dir, image_filename, config) if File.exist?(absolute_image_path)
+      next unless File.exist?(absolute_image_path)
+
+      manifest.record(image_path, digest)
+      register_static_file(site, site_image_path, config)
 
       item.data["image"] ||= {
-        "path" => relative_image_path,
-        "width" => JekyllOgImage.config.canvas.width,
-        "height" => JekyllOgImage.config.canvas.height,
+        "path" => File.join("/", site_image_path), # Use leading slash for URL
+        "width" => item_config.canvas.width,
+        "height" => item_config.canvas.height,
         "alt" => item.data["title"]
       }
     end
@@ -65,7 +71,7 @@ class JekyllOgImage::Generator < Jekyll::Generator
     when "posts"
       site.posts.docs
     when "pages"
-      site.pages.reject { |page| !page.html? }
+      site.pages.select(&:html?)
     else
       if site.collections.key?(type)
         site.collections[type].docs
@@ -76,104 +82,145 @@ class JekyllOgImage::Generator < Jekyll::Generator
     end
   end
 
-  def register_static_file(site, base_output_dir, image_filename, config)
-    relative_path = File.join("/", base_output_dir, image_filename)
+  # The source file's path without its collection directory and extension, which is
+  # unique within the site: "_posts/2024-01-01-hello.md" => "2024-01-01-hello",
+  # "blog/index.md" => "blog/index".
+  def image_basename(item)
+    path = item.relative_path.delete_prefix("/")
+    path = path.delete_prefix("#{item.collection.relative_directory}/") if item.respond_to?(:collection) && item.collection
+    path = path.delete_suffix(File.extname(path))
+
+    path.split("/").map { |segment| slugify_path_segment(segment) }.join("/")
+  end
+
+  def slugify_path_segment(segment)
+    slug = Jekyll::Utils.slugify(segment)
+    # A name made only of characters slugify removes, e.g. emoji
+    slug.empty? ? Digest::SHA256.hexdigest(segment)[0, 12] : slug
+  end
+
+  # Changes whenever anything that affects the rendered image changes
+  def image_digest(site, item, config)
+    inputs = [
+      JekyllOgImage::VERSION,
+      config.canvas.to_h,
+      config.header.to_h,
+      config.content.to_h,
+      config.image.to_h,
+      config.border_bottom&.to_h,
+      config.metadata.to_h,
+      config.domain,
+      item.data["title"],
+      config.metadata.fields.map { |field| metadata_value_for(item, field, config) },
+      file_digest(site, config.image.path),
+      file_digest(site, config.canvas.background_image)
+    ]
+
+    Digest::SHA256.hexdigest(JSON.generate(inputs))
+  end
+
+  def file_digest(site, path)
+    return unless path
+
+    absolute_path = File.join(site.source, path)
+    @file_digests[absolute_path] ||= Digest::SHA256.file(absolute_path).hexdigest if File.file?(absolute_path)
+  end
+
+  def register_static_file(site, site_image_path, config)
+    relative_path = File.join("/", site_image_path)
     return if site.static_files.any? { |file| file.relative_path == relative_path }
 
+    # Leading slash in dir, as Jekyll's reader does, so relative_path matches the check above
     static_file = Jekyll::StaticFile.new(
       site,
       site.source,
-      base_output_dir,
-      image_filename
+      File.dirname(relative_path),
+      File.basename(relative_path)
     )
 
     site.static_files << static_file
-    Jekyll.logger.info "Jekyll Og Image:", "Added #{base_output_dir}/#{image_filename} to static files" if config.verbose?
+    Jekyll.logger.info "Jekyll Og Image:", "Added #{site_image_path} to static files" if config.verbose?
   end
 
-  def generate_image_for_document(site, item, path, base_config)
-    config = base_config.merge!(item.data["og_image"] || {})
-
-    return unless config.enabled?
+  def generate_image_for_document(site, item, path, config)
+    layout = JekyllOgImage::Layout.new(config)
 
     canvas = generate_canvas(site, config)
-    canvas = add_border_bottom(canvas, config) if config.border_bottom
-    canvas = add_image(canvas, File.read(File.join(site.config["source"], config.image.path)), config) if config.image.path
-    canvas = add_header(canvas, item, config)
-    canvas = add_metadata(canvas, item, config)
-    canvas = add_domain(canvas, item, config) if config.domain
+    canvas = add_border_bottom(canvas, config, layout) if config.border_bottom
+    logo = read_source_file(site, config.image.path, "og_image.image.path") if config.image.path
+    canvas = add_image(canvas, logo, config, layout) if logo
+    canvas = add_header(canvas, item, config, layout)
+    canvas = add_metadata(canvas, item, config, layout)
+    canvas = add_domain(canvas, config, layout) if config.domain
 
     canvas.save(path)
   end
 
   def generate_canvas(site, config)
-    background_image = if config.canvas.background_image
-      bg_path = File.join(site.config["source"], config.canvas.background_image.gsub(/^\//, ""))
-      File.exist?(bg_path) ? File.read(bg_path) : nil
+    if config.canvas.background_image
+      background_image = read_source_file(site, config.canvas.background_image, "og_image.canvas.background_image")
     end
 
-    JekyllOgImage::Element::Canvas.new(JekyllOgImage.config.canvas.width, JekyllOgImage.config.canvas.height,
+    JekyllOgImage::Element::Canvas.new(config.canvas.width, config.canvas.height,
       background_color: config.canvas.background_color,
       background_image: background_image
     )
   end
 
-  def add_border_bottom(canvas, config)
-    canvas.border(config.border_bottom.width,
+  def read_source_file(site, path, option)
+    absolute_path = File.join(site.source, path)
+    return File.binread(absolute_path) if File.file?(absolute_path)
+
+    # Warn once per build, not once per document
+    Jekyll.logger.warn "Jekyll Og Image:", "#{option} file not found: #{path}, skipping it" if @missing_files.add?(path)
+    nil
+  end
+
+  def add_border_bottom(canvas, config, layout)
+    canvas.border(layout.border_width,
       position: :bottom,
       fill: config.border_bottom.fill
     )
   end
 
-  def add_image(canvas, image_data, config)
-    image_config = config.image
+  def add_image(canvas, image_data, config, layout)
     canvas.image(image_data,
-      gravity: image_config.gravity,
-      width: image_config.width,
-      height: image_config.height,
-      radius: image_config.radius
-    ) { |_canvas, _text| { x: image_config.position[:x], y: image_config.position[:y] } }
+      gravity: config.image.gravity,
+      width: layout.logo_width,
+      height: layout.logo_height,
+      radius: layout.logo_radius
+    ) { |_canvas, _image| layout.logo_position }
   end
 
-  def add_header(canvas, item, config)
+  def add_header(canvas, item, config, layout)
     title = item.data["title"] || "Untitled"
     full_title = "#{config.header.prefix}#{title}#{config.header.suffix}"
 
-    # Calculate available width for header text to avoid overlap with image
-    header_width = if config.image.path
-      # Canvas width - left margin - right margin - image width - spacing
-      # 1200 - 80 - 80 - image_width - 30 (spacing)
-      1040 - config.image.width - 30
-    else
-      1040
-    end
-
     canvas.text(full_title,
-      width: header_width,
+      width: layout.header_width,
+      height: layout.header_max_height(content_line_height(config, layout)),
       color: config.header.color,
-      dpi: 400,
+      dpi: layout.header_dpi,
       font: config.header.font_family
-    ) { |_canvas, _text| { x: 80, y: 100 } }
+    ) { |_canvas, _text| { x: layout.margin, y: layout.header_top } }
   end
 
-  def add_metadata(canvas, item, config)
-    metadata_text = metadata_text_for(item, config)
+  def add_metadata(canvas, item, config, layout)
+    metadata_text = metadata_text_for(item, config, layout)
     return canvas if metadata_text.empty?
 
-    metadata_width = metadata_width_for(config)
-
     canvas.text(metadata_text,
       gravity: :sw,
-      width: metadata_width,
+      width: metadata_width_for(config, layout),
       color: config.content.color,
-      dpi: 150,
+      dpi: layout.content_dpi,
       font: config.content.font_family
-    ) { |_canvas, _text| { x: 80, y: config.margin_bottom } }
+    ) { |_canvas, _text| { x: layout.margin, y: layout.bottom } }
   end
 
-  def metadata_text_for(item, config)
+  def metadata_text_for(item, config, layout)
     metadata_parts = []
-    metadata_width = metadata_width_for(config)
+    metadata_width = metadata_width_for(config, layout)
 
     config.metadata.fields.each do |field|
       metadata_value = metadata_value_for(item, field, config)
@@ -181,7 +228,7 @@ class JekyllOgImage::Generator < Jekyll::Generator
 
       if field == "description"
         candidate_text = (metadata_parts + [ metadata_value ]).join(config.metadata.separator)
-        next unless metadata_text_fits_single_line?(candidate_text, metadata_width, config)
+        next unless metadata_text_fits_single_line?(candidate_text, metadata_width, config, layout)
       end
 
       metadata_parts << metadata_value
@@ -195,7 +242,7 @@ class JekyllOgImage::Generator < Jekyll::Generator
     when "date"
       item.respond_to?(:date) && item.date ? item.date.strftime(config.metadata.date_format) : nil
     when "tags"
-      return nil unless item.data["tags"]&.is_a?(Array) && item.data["tags"].any?
+      return nil unless item.data["tags"].is_a?(Array) && item.data["tags"].any?
 
       item.data["tags"].map { |tag| "##{tag}" }.join(" ")
     else
@@ -204,34 +251,38 @@ class JekyllOgImage::Generator < Jekyll::Generator
     end
   end
 
-  def metadata_width_for(config)
-    config.domain ? 600 : 1040
+  # The metadata line shares the bottom row with the domain
+  def metadata_width_for(config, layout)
+    return layout.content_width unless config.domain
+
+    layout.content_width - render_content_text(config.domain, config, layout).width - layout.gap
   end
 
-  def metadata_text_fits_single_line?(text, metadata_width, config)
-    options = {
-      width: metadata_width,
-      dpi: 150,
-      font: config.content.font_family,
-      align: :low
-    }
-    options[:wrap] = :word if Vips.at_least_libvips?(8, 14)
+  def metadata_text_fits_single_line?(text, metadata_width, config, layout)
+    rendered_height = render_content_text(text, config, layout, width: metadata_width).height
 
-    single_line_height = Vips::Image.text("Ay", **options).height
-    rendered_height = Vips::Image.text(text, **options).height
+    rendered_height <= (content_line_height(config, layout) * 1.6)
+  end
 
-    rendered_height <= (single_line_height * 1.6)
+  def content_line_height(config, layout)
+    render_content_text("Ay", config, layout).height
   end
 
+  def render_content_text(text, config, layout, width: nil)
+    options = { dpi: layout.content_dpi, font: config.content.font_family, align: :low }
+    options[:width] = width if width
+    options[:wrap] = :word if width && Vips.at_least_libvips?(8, 14)
+
+    Vips::Image.text(JekyllOgImage::Element::Text.escape_markup(text), **options)
+  end
 
-  def add_domain(canvas, _item, config)
-    y_pos = config.margin_bottom
 
+  def add_domain(canvas, config, layout)
     canvas.text(config.domain,
       gravity: :se,
       color: config.content.color,
-      dpi: 150,
+      dpi: layout.content_dpi,
       font: config.content.font_family
-    ) { |_canvas, _text| { x: 80, y: y_pos } }
+    ) { |_canvas, _text| { x: layout.margin, y: layout.bottom } }
   end
 end

data/lib/jekyll_og_image/layout.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Positions and sizes for an image. Everything, including the pixel sizes in the
+# configuration (logo, border), is designed for a 1200px-wide canvas and scaled
+# with the canvas width, so any canvas size keeps the same proportions.
+class JekyllOgImage::Layout
+  REFERENCE_WIDTH = 1200.0
+
+  def initialize(config)
+    @config = config
+    @scale = config.canvas.width / REFERENCE_WIDTH
+  end
+
+  # Left, right and bottom margin
+  def margin
+    scaled(80)
+  end
+
+  def header_top
+    scaled(100)
+  end
+
+  def header_dpi
+    scaled(400)
+  end
+
+  def content_dpi
+    scaled(150)
+  end
+
+  # Space between the header and whatever is next to or below it
+  def gap
+    scaled(30)
+  end
+
+  def border_width
+    scaled(@config.border_bottom&.width || 0)
+  end
+
+  # Distance from the bottom edge to the metadata line, above the border
+  def bottom
+    margin + border_width
+  end
+
+  def logo_width
+    scaled(@config.image.width)
+  end
+
+  def logo_height
+    scaled(@config.image.height)
+  end
+
+  def logo_radius
+    scaled(@config.image.radius) if @config.image.radius
+  end
+
+  def logo_position
+    { x: scaled(@config.image.position[:x]), y: scaled(@config.image.position[:y]) }
+  end
+
+  def content_width
+    @config.canvas.width - 2 * margin
+  end
+
+  # Leaves room for the logo next to the header
+  def header_width
+    @config.image.path ? content_width - logo_width - gap : content_width
+  end
+
+  # How tall the header can be without reaching the metadata line
+  def header_max_height(metadata_line_height)
+    @config.canvas.height - header_top - bottom - metadata_line_height - gap
+  end
+
+  private
+
+  def scaled(value)
+    (value * @scale).round
+  end
+end

data/lib/jekyll_og_image/manifest.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Remembers a digest of the inputs each image was generated from, so images are
+# regenerated only when something that affects them changes.
+#
+# Stored as a dotfile in the output directory, which Jekyll never publishes.
+class JekyllOgImage::Manifest
+  FILENAME = ".jekyll-og-image.json"
+
+  def initialize(dir)
+    @path = File.join(dir, FILENAME)
+    @previous = load
+    @current = {}
+  end
+
+  def fresh?(image_path, digest)
+    @current.fetch(image_path) { @previous[image_path] } == digest
+  end
+
+  def record(image_path, digest)
+    @current[image_path] = digest
+  end
+
+  # Writes the images recorded during this build. Entries for images that weren't
+  # recorded (deleted or disabled documents) are dropped.
+  def save
+    entries = @current.sort.to_h
+    return if entries == @previous
+
+    FileUtils.mkdir_p(File.dirname(@path))
+    File.write(@path, JSON.pretty_generate(entries))
+  end
+
+  private
+
+  def load
+    JSON.parse(File.read(@path))
+  rescue Errno::ENOENT, JSON::ParserError
+    {}
+  end
+end

data/lib/jekyll_og_image/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllOgImage
-  VERSION = "2.1.0"
+  VERSION = "3.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-og-image
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Igor Alexandrov
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: jekyll-seo-tag
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.8'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '2.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -71,20 +57,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: csv
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 email:
 - igor.alexandrov@gmail.com
 executables: []
@@ -97,6 +69,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/icon.png
+- assets/icon.svg
 - examples/1.png
 - examples/2.png
 - examples/3.png
@@ -110,6 +84,8 @@ files:
 - lib/jekyll_og_image/element/image.rb
 - lib/jekyll_og_image/element/text.rb
 - lib/jekyll_og_image/generator.rb
+- lib/jekyll_og_image/layout.rb
+- lib/jekyll_og_image/manifest.rb
 - lib/jekyll_og_image/version.rb
 homepage: https://github.com/igor-alexandrov/jekyll-og-image
 licenses:
@@ -130,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Jekyll plugin to generate GitHub-style open graph images
 test_files: []