Jekyll OG Image

A Jekyll plugin to automatically generate open graph images for posts.

Add this line to your site's Gemfile:

  gem 'jekyll-seo-tag'
  gem 'jekyll-og-image'

And then add this line to your site's _config.yml:

plugins:
  - jekyll-seo-tag
  - jekyll-og-image

The plugin requires Ruby 3.2 or newer and libvips. 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.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true

      - name: Update apt
        env:
          DEBIAN_FRONTEND: noninteractive
        run: sudo apt-get update -qq

      - name: Install libvips
        env:
          DEBIAN_FRONTEND: noninteractive
        run: sudo apt-get install --fix-missing libvips

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Build with Jekyll
        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

Jekyll OG Image works together with the 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.

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.

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.

The plugin can be configured in the _config.yml file or in the post's front matter.

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 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, 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). 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

• 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. 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. 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: ""
  • suffix – Text to append to the title. Default: ""

• content – The content configuration options:

  • font_family – The font family of the content text. Default: Helvetica, Regular
  • color – The color of the content text. Default: #535358

• border_bottom – The border bottom configuration options:

  • 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

• image – Logo/image configuration options. Can be a string (legacy format) or an object with the following options:

  • path – Path to the image file. Note: Use JPEG format for best compatibility. PNG images with transparency may not render correctly. Default: nil
  • width – The width of the logo in pixels. Default: 150
  • 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, 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"]
  • separator – Text to separate multiple metadata fields. Default: " • "
  • date_format – Date format string for the date field. Default: "%B %d, %Y"

Configuration can be defined on the site level or on the post level.

For a side wide level configuration, edit your _config.yml, for a post level configuration, edit the post's front matter.

# _config.yml
og_image:
  collections: ["posts", "pages"]
  output_dir: "assets/images/og"
  domain: "igor.works"
  border_bottom:
    width: 20
    fill:
      - "#4285F4"

# _config.yml
og_image:
  output_dir: "assets/images/og"
  image: "/assets/images/igor.jpeg"
  domain: "igor.works"
  border_bottom:
    width: 20
    fill:
      - "#820C02"
      - "#A91401"
      - "#D51F06"
      - "#DE3F24"
      - "#EDA895"

# _config.yml
og_image:
  output_dir: "/assets/og"
  image: "/assets/images/igor.jpeg"
  canvas:
    background_color: "#F9E065"
  header:
    font_family: "Roboto, Bold"
    color: "#333333"
  content:
    font_family: "Roboto, Regular"
    color: "#333333"
  force: false
  domain: "igor.works"
  border_bottom:
    width: 50
    fill:
      - "#002B7F"
      - "#FCD116"
      - "#CE1126"

# _config.yml
og_image:
  output_dir: "/assets/og"
  image: "/assets/images/igor.jpeg"
  header:
    font_family: "Roboto, Bold"
    color: "#333333"
  content:
    font_family: "Roboto, Bold"
    color: "#333333"
  force: false
  domain: "igor.works"

# _posts/2024-02-15-traefik-tunning-for-rails-applications-part-1.md
---
title: Traefik Tuning for Rails Applications (part 1)
layout: post
tags:
  - Rails
  - Traefik
  - Kamal
og_image:
  canvas:
    background_image: "/assets/images/bc_3.jpg"

# _config.yml
og_image:
  domain: "igor.works"
  image:
    path: "/assets/images/logo.png"
    width: 100
    height: 100
    radius: 20
    position:
      x: 60
      y: 60
  header:
    prefix: "📖 "
    suffix: " - My Blog"
  metadata:
    fields: ["author", "date", "reading_time"]
    separator: " | "
    date_format: "%d %B %Y"

This configuration:

• Adjusts the logo size to 100x100px with less rounded corners
• Adds a book emoji prefix and " - My Blog" suffix to titles
• Shows author, date, and reading_time in the metadata section
• Uses a pipe separator between metadata fields
• Formats dates as "15 February 2024"

• Fork it (https://github.com/igor-alexandrov/jekyll-og-image)
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new Pull Request

The gem is available as open source under the terms of the MIT License.