This plugin helps to create Open Graph images in Eleventy using HTML1 within any supported template language and CSS2 via satori. No headless browser will be harmed 😉.
Install the package:
npm install eleventy-plugin-og-image --save-devIt'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',
},
],
},
});
}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
});
};Create an OG-image-template anywhere in the input directory. Use only the supported HTML elements1 and CSS properties2. CSS in <style> tags will be inlined, remote images fetched. Shortcode scoped data from the parent template is available. Additionally, some options will be available in the eleventyPluginOgImage key. This is an example og-image.og.njk:
<style>
.root {
width: 100%;
height: 100%;
display: flex;
flex-direction: column;
align-items: center;
background: linear-gradient(135deg, #ef629f, #eecda3);
}
.title {
color: white;
font-size: 80px;
margin: auto 0;
}
</style>
<div class="root">
<h1 class="title">{{ title }}</h1>
</div>Call the ogImage shortcode inside the <head> 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!" } %}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):
<meta property="og:image" content="/og-images/s0m3h4sh.png" />For applied usage see the example.
Tip
The template language of the page and OG-image-template can be mixed or matched.
The following options can be passed when adding the plugin:
| Property | Type | Default | |
|---|---|---|---|
inputFileGlob |
glob |
**/*.og.* |
This must match the OG-image-templates to prevent HTML compilation. |
hashLength |
number |
8 |
|
outputFileExtension |
sharp output file formats | png |
|
outputDir |
string |
og-images |
Directory into which OG images will be emitted. Relative to eleventy output. |
previewDir |
string |
${outputDir}/preview |
Directory used for preview during watch or serve. Relative to eleventy output. |
urlPath |
string |
${outputDir} |
URL-prefix which will be used in returned meta-tags. |
outputFileSlug |
function |
See source | Generation of the output file slug, must be url safe and exclude the file extension. |
shortcodeOutput |
function |
See source | Change the HTML returned by the shortcode in pages. |
satoriOptions |
satori options | { width: 1200, height: 630, fonts: [] } |
If an OG-image-template contains text, it's required to load a font (example). |
sharpOptions |
sharp output options | undefined |
Options must be corresponding to chosen outputFileExtension. |
OgImage |
class CustomOgImage extends OgImage |
OgImage |
Extend the OgImage class for maximum customization. |
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.
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.
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,
});
}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();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 }}.
This plugin is deeply inspired by @vercel/og.
Furthermore, it would not be possible without:
Footnotes
-
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. ↩ ↩2