jekyll-templated-og-image 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50b0f286a3f3c10a3d1a38217511af8ed2f6d9a4d32ae892c80fe9e47a127f91
+  data.tar.gz: 330e588e2b3de5e8598f18a6acc5fbbb274c5e5edc98e9b3b3916be9bb52f2d6
+SHA512:
+  metadata.gz: 2608360a20dcd95ad91392301b9fd05e7c1e878f5374962ce7cd03e9a7f93c49e8746f4cdb4a7714ce930afbda8344a1ba44387d41b5bfc80899ee44f727cd34
+  data.tar.gz: 204dbf90388771915f70085c1795b5fd2363846c41d04667ea8e055f108c1553c02f5038508510b2d561a008e958a88276b0237f1c018280d4ddbf1868035e66

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 catskull
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# jekyll-og-image
+
+Jekyll plugin that automatically generates Open Graph images for your posts and pages using headless Chrome.
+
+## Requirements
+
+- Ruby >= 3.0
+- Jekyll >= 4.0
+- Chrome or Chromium installed on the machine
+
+## Installation
+
+Add to your site's Gemfile. To run in development only:
+
+```ruby
+group :development, :jekyll_plugins do
+  gem "jekyll-og-image"
+end
+```
+
+Then run `bundle install`. Do not add it to the `plugins:` list in `_config.yml` — Bundler loads it automatically via the `:jekyll_plugins` group.
+
+## Usage
+
+This plugin is intended to run in development only. Generate images locally and commit them to your repository — they will be served in production without the plugin running.
+
+Generated images are saved to `assets/og/{slug}.png` and copied back to your source directory so they persist across builds and can be committed. On subsequent builds, existing images are skipped.
+
+Since the plugin does not run in production, do not rely on `page.og_image` being set. Instead, derive the image path from the page URL directly — it is always predictable:
+
+```html
+{% assign og_slug = page.url | remove_first: "/" | replace: "/", "-" | remove: ".html" %}
+{% if og_slug == "" %}{% assign og_slug = "index" %}{% endif %}
+<meta property="og:image" content="{{ site.url }}/assets/og/{{ og_slug }}.png">
+```
+
+## Configuration
+
+All configuration is optional. Add an `og_image` key to `_config.yml`:
+
+```yaml
+og_image:
+  output_dir: assets/og    # where to write generated images
+  layouts_dir: _og/layouts # where layout files live
+  force: false             # set true to regenerate existing images
+  quiet: false             # set true to suppress log output
+  templates:
+    - collection: posts
+      template: _og/post.html
+    - collection: page
+      template: _og/page.html
+    - collection: recipes
+      template: _og/recipe.html
+    - path: /recipes/my-special-recipe
+      template: _og/special.html
+```
+
+### Template rules
+
+Only documents covered by at least one rule are processed. Each rule matches by either:
+
+- `collection` — the collection name: `posts`, `page`, or any custom collection (e.g. `recipes`)
+- `path` — a glob matched against the document's URL (e.g. `/blog/**`)
+
+`path` rules always take priority over `collection` rules, regardless of their order in the config. This lets you override the template for a specific page even if it belongs to a collection that has its own rule.
+
+If a matching rule has no `template` key, the gem's built-in default template is used.
+
+Set `template: false` to skip OG image generation for matched documents:
+
+```yaml
+og_image:
+  templates:
+    - collection: page
+      template: false
+```
+
+### Custom templates
+
+Templates are Liquid files. The following variables are available:
+
+Templates have access to the same variables as any Jekyll layout:
+
+| Variable | Description |
+|---|---|
+| `page` | All front matter and computed fields for the document (e.g. `page.title`, `page.url`, `page.date`, `page.tags`) |
+| `site` | Site-wide data from `_config.yml` and Jekyll (e.g. `site.title`, `site.posts`, `site.data`) |
+
+Templates support layouts via front matter, similar to Jekyll:
+
+```
+_og/
+  layouts/
+    base.html      ← shared structure, renders {{ content }}
+  post.html        ← post-specific, declares layout: base
+  page.html        ← page-specific, declares layout: base
+```
+
+**`_og/post.html`:**
+```html
+---
+layout: base
+---
+<div class="post-card">{{ title }}</div>
+```
+
+**`_og/layouts/base.html`:**
+```html
+<html>
+  <body style="width:1200px;height:630px">
+    {{ content }}
+  </body>
+</html>
+```
+
+Images are captured at 1200×630px, the standard OG image size.

data/lib/jekyll-templated-og-image/config.rb

@@ -0,0 +1,21 @@
+module JekyllOgImage
+  class Config
+    DEFAULTS = {
+      "output_dir" => "assets/og",
+      "layouts_dir" => "_og/layouts",
+      "force" => false,
+      "quiet" => false,
+      "templates" => []
+    }.freeze
+
+    def initialize(jekyll_config)
+      @config = DEFAULTS.merge(jekyll_config.fetch("og_image", {}))
+    end
+
+    def output_dir = @config["output_dir"]
+    def layouts_dir = @config["layouts_dir"]
+    def force? = @config["force"]
+    def quiet? = @config["quiet"]
+    def template_rules = @config["templates"]
+  end
+end

data/lib/jekyll-templated-og-image/generator.rb

@@ -0,0 +1,83 @@
+require "ferrum"
+require "fileutils"
+require_relative "config"
+require_relative "template_resolver"
+
+module JekyllOgImage
+  class Generator < Jekyll::Generator
+    safe true
+    priority :low
+
+    def generate(site)
+      @site = site
+      @config = Config.new(site.config)
+      @resolver = TemplateResolver.new(@config.template_rules, site.source, @config.layouts_dir, site)
+      @output_dir = File.join(site.dest, @config.output_dir)
+      @source_dir = File.join(site.source, @config.output_dir)
+
+      browser = Ferrum::Browser.new(headless: true, browser_options: { "font-render-hinting" => "none" })
+      browser.resize(width: 1200, height: 630)
+
+      all_docs = site.posts.docs + site.pages + site.collections.values.flat_map(&:docs)
+
+      documents = []
+      @config.template_rules.each do |rule|
+        if (collection = rule["collection"])
+          case collection
+          when "posts" then documents += site.posts.docs
+          when "page"  then documents += site.pages
+          else              documents += site.collections[collection]&.docs || []
+          end
+        elsif (glob = rule["path"])
+          documents += all_docs.select { |doc| File.fnmatch(glob, doc.url, File::FNM_PATHNAME) }
+        end
+      end
+      documents.uniq.reject { |doc| doc.url.end_with?(".xml", ".csv") }.each do |doc|
+        generate_image(browser, doc)
+      end
+    ensure
+      browser&.quit
+    end
+
+    private
+
+    def generate_image(browser, doc)
+      slug = slug_for(doc)
+      output_path = File.join(@output_dir, "#{slug}.png")
+      source_path = File.join(@source_dir, "#{slug}.png")
+
+      if File.exist?(source_path) && !@config.force?
+        doc.data["og_image"] = "/#{@config.output_dir}/#{slug}.png"
+        return
+      end
+
+      log "OG Image:", "Generating #{slug}.png"
+
+      html = @resolver.render(doc, @site.site_payload.merge("page" => doc.to_liquid))
+      return log("OG Image:", "Skipping #{slug}") if html.nil?
+
+      FileUtils.mkdir_p(@output_dir)
+      browser.go_to("data:text/html;charset=utf-8,#{ERB::Util.url_encode(html)}")
+      browser.network.wait_for_idle
+      browser.screenshot(path: output_path)
+
+      FileUtils.mkdir_p(@source_dir)
+      FileUtils.cp(output_path, source_path)
+
+      @site.static_files << Jekyll::StaticFile.new(
+        @site, @site.source, @config.output_dir, "#{slug}.png"
+      )
+
+      doc.data["og_image"] = "/#{@config.output_dir}/#{slug}.png"
+      log "OG Image:", "Generated #{slug}.png"
+    end
+
+    def log(topic, message)
+      Jekyll.logger.info(topic, message) unless @config.quiet?
+    end
+
+    def slug_for(doc)
+      doc.url.gsub("/", "-").gsub(/^-|-$/, "").then { |s| s.empty? ? "index" : s }
+    end
+  end
+end

data/lib/jekyll-templated-og-image/template/og-image.html

@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=1200, height=630">
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      width: 1200px;
+      height: 630px;
+      display: flex;
+      flex-direction: column;
+      justify-content: flex-end;
+      padding: 64px;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+      background: #0f172a;
+      color: #f8fafc;
+      overflow: hidden;
+    }
+
+    .accent {
+      display: block;
+      width: 64px;
+      height: 6px;
+      background: #6366f1;
+      border-radius: 3px;
+      margin-bottom: 32px;
+    }
+
+    .title {
+      font-size: 64px;
+      font-weight: 700;
+      line-height: 1.1;
+      letter-spacing: -0.02em;
+      color: #f8fafc;
+      max-width: 900px;
+      margin-bottom: 40px;
+    }
+
+    .meta {
+      display: flex;
+      align-items: center;
+      gap: 24px;
+    }
+
+    .date {
+      font-size: 22px;
+      color: #94a3b8;
+      font-weight: 500;
+    }
+
+    .tags {
+      display: flex;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+
+    .tag {
+      font-size: 18px;
+      font-weight: 600;
+      color: #818cf8;
+      background: rgba(99, 102, 241, 0.15);
+      padding: 4px 14px;
+      border-radius: 999px;
+    }
+
+    .site {
+      position: absolute;
+      top: 64px;
+      right: 64px;
+      font-size: 20px;
+      font-weight: 600;
+      color: #475569;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+    }
+  </style>
+</head>
+<body>
+  {% if site.title != "" %}<span class="site">{{ site.title }}</span>{% endif %}
+  <span class="accent"></span>
+  <h1 class="title">{{ page.title | default: page.url }}</h1>
+  <div class="meta">
+    {% if page.date %}<span class="date">{{ page.date | date: "%B %-d, %Y" }}</span>{% endif %}
+    {% if page.tags.size > 0 %}
+    <div class="tags">
+      {% for tag in page.tags %}<span class="tag">{{ tag }}</span>{% endfor %}
+    </div>
+    {% endif %}
+  </div>
+</body>
+</html>

data/lib/jekyll-templated-og-image/template_resolver.rb

@@ -0,0 +1,77 @@
+require "liquid"
+require "yaml"
+
+module JekyllOgImage
+  class TemplateResolver
+    DEFAULT_TEMPLATE_PATH = File.expand_path("template/og-image.html", __dir__)
+
+    def initialize(rules, site_source, layouts_dir, site)
+      @site_source = site_source
+      @layouts_dir = File.expand_path(layouts_dir, site_source)
+      @site = site
+      @rules = rules.sort_by { |r| r["path"] ? 0 : 1 }
+      @cache = {}
+    end
+
+    def render(doc, variables)
+      path = path_for(doc)
+      return nil if path.nil?
+      render_file(path, variables)
+    end
+
+    private
+
+    def render_file(path, variables)
+      front_matter, template = @cache[path] ||= parse_template(path)
+      content = template.render!(variables, registers: { site: @site })
+
+      if (layout_name = front_matter["layout"])
+        layout_path = File.join(@layouts_dir, "#{layout_name}.html")
+        render_file(layout_path, variables.merge(front_matter).merge("content" => content))
+      else
+        content
+      end
+    end
+
+    def parse_template(path)
+      front_matter, body = parse_front_matter(File.read(path))
+      [front_matter, Liquid::Template.parse(body)]
+    end
+
+    def path_for(doc)
+      @rules.each do |rule|
+        next unless matches?(rule, doc)
+        return nil if rule["template"] == false
+        return File.expand_path(rule["template"], @site_source) if rule["template"]
+        return DEFAULT_TEMPLATE_PATH
+      end
+      DEFAULT_TEMPLATE_PATH
+    end
+
+    def matches?(rule, doc)
+      if (collection = rule["collection"])
+        doc_type(doc) == collection.to_s
+      elsif (glob = rule["path"])
+        File.fnmatch(glob, doc.url, File::FNM_PATHNAME)
+      else
+        true
+      end
+    end
+
+    def doc_type(doc)
+      if doc.respond_to?(:collection)
+        doc.collection.label
+      else
+        "page"
+      end
+    end
+
+    def parse_front_matter(raw)
+      if raw =~ /\A---\s*\n(.*?\n?)---\s*\n(.*)/m
+        [YAML.safe_load($1) || {}, $2]
+      else
+        [{}, raw]
+      end
+    end
+  end
+end

data/lib/jekyll-templated-og-image.rb

@@ -0,0 +1,4 @@
+require "jekyll"
+require "jekyll-templated-og-image/config"
+require "jekyll-templated-og-image/template_resolver"
+require "jekyll-templated-og-image/generator"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-templated-og-image
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- catskull
+bindir: bin
+cert_chain: []
+date: 1980-01-02 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-templated-og-image.rb
+- lib/jekyll-templated-og-image/config.rb
+- lib/jekyll-templated-og-image/generator.rb
+- lib/jekyll-templated-og-image/template/og-image.html
+- lib/jekyll-templated-og-image/template_resolver.rb
+homepage: https://github.com/catskull/jekyll-og-image
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate Open Graph images for Jekyll pages and posts
+test_files: []