Eleventy Plugin OG Image

This plugin helps to create Open Graph images in Eleventy using HTML[^1] within any supported template language and CSS[^2] via satori. No headless browser will be harmed 😉.

Usage

Install the package:

npm install eleventy-plugin-og-image --save-dev

ESM

It's preferred to use this plugin within ESM Eleventy projects. Read more about ESM vs CommonJS on the Eleventy documentation.

import EleventyPluginOgImage from 'eleventy-plugin-og-image';

export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    satoriOptions: {
      fonts: [
        {
          name: 'Inter',
          data: fs.readFileSync('../path/to/font-file/inter.woff'),
          weight: 700,
          style: 'normal',
        },
      ],
    },
  });
}

CommonJS

> [!NOTE] > This plugin is written in ESM, therefore require is not possible. If the .eleventy.js config uses CommonJS, switch to async and create a dynamic import as shown below.

module.exports = async function (eleventyConfig) {
  const EleventyPluginOgImage = (await import('eleventy-plugin-og-image')).default;

  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    // See above for example config
  });
};

Add a Template

Create an OG-image-template anywhere in the input directory. Use only the supported HTML elements[^1] and CSS properties[^2]. CSS in `

Call the ogImage shortcode inside the `` in a template or layout. The first argument is the filePath of the OG-image-template (required, relative to the Eleventy input directory). The second argument is for data (optional). Usage example in Nunjucks, e.g. example-page.njk:

{% ogImage "./og-image.og.njk", { title: "Hello World!" } %}

Result

Generated OG image _site/og-images/s0m3h4sh.png:

HTML output generated by the shortcode into _site/example-page/index.html (can be modified via the shortcodeOutput option):

For applied usage see the example.

> [!TIP] > The template language of the page and OG-image-template can be mixed or matched.

Configuration

The following options can be passed when adding the plugin:

Preview Mode

During development with watch or serve the OG image files are also copied into the previewDir, named by the url slug of the pages they are generated from. Next to it there is a HTML placed which shows the generated HTML, SVG and output image. The previewDir will be deleted during a production build.

Caching

For better performance OG images are cached based on a hash from generated HTML and output options. If the file already exists, further transformations are skipped.

Advanced Usage

Extending OgImage Class

It's possible to extend and overwrite any of the functions from the OgImage class. The custom class is passed as the OgImage parameter to the plugin.

import EleventyPluginOgImage from 'eleventy-plugin-og-image';
import { OgImage } from 'eleventy-plugin-og-image/og-image';

export class CustomOgImage extends BaseOgImage {
  async shortcodeOutput() {
    return this.outputUrl();
  }
}

/** @param {import('@11ty/eleventy/src/UserConfig').default} eleventyConfig */
export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(EleventyPluginOgImage, {
    OgImage: CustomOgImage,
  });
}

Custom Shortcode

A custom shortcode can be created by using the OgImage class.

import { OgImage } from 'eleventy-plugin-og-image/og-image';

const image = await new OgImage({ inputPath, data, options, templateConfig }).render();

Capture Output URL

The plugins shortcode create a meta tag per default, modify the shortcodeOutput option or class function to directly return the outputUrl:

eleventyConfig.addPlugin(EleventyPluginOgImage, {
  async shortcodeOutput(ogImage) {
    return ogImage.outputUrl();
  },
});

Furthermore, it's possible to capture the outputUrl to a variable, e.g. in Nunjucks:

{% setAsync "ogOutputUrl" -%}
    {% ogImage "./og-image.og.njk", { title: "Hello World!" } %}
{%- endsetAsync %}

And use it anywhere afterward with {{ ogOutputUrl }}.

Acknowledgements & Attributions

This plugin is deeply inspired by @vercel/og.

Furthermore, it would not be possible without:

• satori
• resvg/resvg-js
• sharp

[^1]: Only a subset of HTML elements is supported by satori.

[^2]: Only a subset of CSS properties are supported by yoga-layout, which is used by satori.