{"id":15283969,"url":"https://github.com/kiwikilian/eleventy-plugin-og-image","last_synced_at":"2025-10-08T21:55:01.082Z","repository":{"id":62175919,"uuid":"556161824","full_name":"KiwiKilian/eleventy-plugin-og-image","owner":"KiwiKilian","description":"Create Open Graph images in Eleventy using your templates, data and CSS. Fast and reproducible, without a headless browser.","archived":false,"fork":false,"pushed_at":"2025-09-22T21:04:43.000Z","size":1993,"stargazers_count":68,"open_issues_count":8,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-27T06:59:17.090Z","etag":null,"topics":["eleventy","eleventy-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KiwiKilian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-23T07:41:06.000Z","updated_at":"2025-09-07T23:05:12.000Z","dependencies_parsed_at":"2023-02-16T16:31:30.209Z","dependency_job_id":"8ee801b8-0553-4828-a0fe-371a50050a24","html_url":"https://github.com/KiwiKilian/eleventy-plugin-og-image","commit_stats":{"total_commits":111,"total_committers":4,"mean_commits":27.75,"dds":0.5045045045045045,"last_synced_commit":"e2f0aa2b2ae48920189782f05f74a0370fa59e81"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/KiwiKilian/eleventy-plugin-og-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KiwiKilian%2Feleventy-plugin-og-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KiwiKilian%2Feleventy-plugin-og-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KiwiKilian%2Feleventy-plugin-og-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KiwiKilian%2Feleventy-plugin-og-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KiwiKilian","download_url":"https://codeload.github.com/KiwiKilian/eleventy-plugin-og-image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KiwiKilian%2Feleventy-plugin-og-image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000689,"owners_count":26082837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eleventy","eleventy-plugin"],"created_at":"2024-09-30T14:48:27.735Z","updated_at":"2025-10-08T21:55:01.077Z","avatar_url":"https://github.com/KiwiKilian.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eleventy Plugin OG Image [![npm](https://img.shields.io/npm/v/eleventy-plugin-og-image?color=blue)](https://www.npmjs.com/package/eleventy-plugin-og-image)\n\nThis plugin helps to create Open Graph images in [Eleventy](https://www.11ty.dev/) using HTML[^1] within any supported template language and CSS[^2] via [satori](https://github.com/vercel/satori). No headless browser will be harmed 😉.\n\n## Usage\n\nInstall the package:\n\n```shell\nnpm install eleventy-plugin-og-image --save-dev\n```\n\n### ESM\n\nIt's preferred to use this plugin within ESM Eleventy projects. Read more about ESM vs CommonJS on the [Eleventy documentation](https://www.11ty.dev/docs/cjs-esm/).\n\n```js\nimport EleventyPluginOgImage from 'eleventy-plugin-og-image';\n\nexport default async function (eleventyConfig) {\n  eleventyConfig.addPlugin(EleventyPluginOgImage, {\n    satoriOptions: {\n      fonts: [\n        {\n          name: 'Inter',\n          data: fs.readFileSync('../path/to/font-file/inter.woff'),\n          weight: 700,\n          style: 'normal',\n        },\n      ],\n    },\n  });\n}\n```\n\n### CommonJS\n\n\u003e [!NOTE]\n\u003e 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.\n\n```js\nmodule.exports = async function (eleventyConfig) {\n  const EleventyPluginOgImage = (await import('eleventy-plugin-og-image')).default;\n\n  eleventyConfig.addPlugin(EleventyPluginOgImage, {\n    // See above for example config\n  });\n};\n```\n\n### Add a Template\n\nCreate an OG-image-template anywhere in the input directory. Use only the supported HTML elements[^1] and CSS properties[^2]. CSS in `\u003cstyle\u003e` tags will be inlined, remote images fetched. [Shortcode scoped data](https://www.11ty.dev/docs/shortcodes/#scoped-data-in-shortcodes) from the parent template is available. Additionally, some options will be available in the `eleventyPluginOgImage` key. This is an example `og-image.og.njk`:\n\n```njk\n\u003cstyle\u003e\n  .root {\n    width: 100%;\n    height: 100%;\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    background: linear-gradient(135deg, #ef629f, #eecda3);\n  }\n\n  .title {\n    color: white;\n    font-size: 80px;\n    margin: auto 0;\n  }\n\u003c/style\u003e\n\n\u003cdiv class=\"root\"\u003e\n  \u003ch1 class=\"title\"\u003e{{ title }}\u003c/h1\u003e\n\u003c/div\u003e\n```\n\nCall the `ogImage` shortcode inside the `\u003chead\u003e` 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`:\n\n```njk\n{% ogImage \"./og-image.og.njk\", { title: \"Hello World!\" } %}\n```\n\n### Result\n\nGenerated OG image `_site/og-images/s0m3h4sh.png`:\n\n![Generated OG image](./assets/og-image.png)\n\nHTML output generated by the shortcode into `_site/example-page/index.html` (can be modified via the `shortcodeOutput` option):\n\n```html\n\u003cmeta property=\"og:image\" content=\"/og-images/s0m3h4sh.png\" /\u003e\n```\n\nFor applied usage see the [example](./example).\n\n\u003e [!TIP]\n\u003e The template language of the page and OG-image-template can be mixed or matched.\n\n## Configuration\n\nThe following options can be passed when adding the plugin:\n\n| Property              | Type                                                                                                     | Default                                   |                                                                                            |\n| --------------------- | -------------------------------------------------------------------------------------------------------- |-------------------------------------------|--------------------------------------------------------------------------------------------|\n| `inputFileGlob`       | `glob`                                                                                                   | `**/*.og.*`                               | This must match the OG-image-templates to prevent HTML compilation.                        |\n| `hashLength`          | `number`                                                                                                 | `8`                                       |                                                                                            |\n| `outputFileExtension` | [sharp output file formats](https://sharp.pixelplumbing.com/api-output#toformat)                         | `png`                                     |                                                                                            |\n| `outputDir`           | `string`                                                                                                 | `og-images`                               | Directory into which OG images will be emitted. Relative to eleventy `output`.             |\n| `previewMode`         | `auto \\| boolean`                                                                                        | `auto`                                    | Enable/disable preview mode.                                                               |\n| `previewDir`          | `string`                                                                                                 | `${outputDir}/preview`                    | Directory used for preview during `watch` or `serve`. Relative to eleventy `output`.       |\n| `urlPath`             | `string`                                                                                                 | `${outputDir}`                            | URL-prefix which will be used in returned meta-tags.                                       |\n| `outputFileSlug`      | `function`                                                                                               | [See source](src/utils/mergeOptions.js)   | Generation of the output file slug, must be url safe and exclude the file extension.       |\n| `shortcodeOutput`     | `function`                                                                                               | [See source](src/utils/mergeOptions.js)   | Change the HTML returned by the shortcode in pages.                                        |\n| `satoriOptions`       | [satori options](https://github.com/search?q=repo:vercel/satori+%22export+type+SatoriOptions%22\u0026type=code) | `{ width: 1200, height: 630, fonts: [] }` | If an OG-image-template contains text, it's **required** to load a font ([example](#esm)). |\n| `sharpOptions`        | [sharp output options](https://sharp.pixelplumbing.com/api-output#toformat)                              | `undefined`                               | Options must be corresponding to chosen `outputFileExtension`.                             |\n| `OgImage`             | `class CustomOgImage extends OgImage`                                                                    | [`OgImage`](src/OgImage.js)               | [Extend the `OgImage`](#extending-ogimage-class) class for maximum customization.          |\n\n## Preview Mode\n\nThe previewMode is intended to ease the styling of OG images. When `previewMode` is set to `auto` (default) the OG images are also copied into the `previewDir` during development with `watch` or `serve`. The files are 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. When not actively working on OG images, performance can be improved by disabling `previewMode`.\n\n## Caching\n\nFor 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.\n\n## Advanced Usage\n\n### Extending OgImage Class\n\nIt's possible to extend and overwrite any of the functions from the [`OgImage`](src/OgImage.js) class. The custom class is passed as the `OgImage` parameter to the plugin.\n\n```js\nimport EleventyPluginOgImage from 'eleventy-plugin-og-image';\nimport { OgImage } from 'eleventy-plugin-og-image/og-image';\n\nexport class CustomOgImage extends BaseOgImage {\n  async shortcodeOutput() {\n    return this.outputUrl();\n  }\n}\n\n/** @param {import('@11ty/eleventy/src/UserConfig').default} eleventyConfig */\nexport default async function (eleventyConfig) {\n  eleventyConfig.addPlugin(EleventyPluginOgImage, {\n    OgImage: CustomOgImage,\n  });\n}\n```\n\n### Custom Shortcode\n\nA custom shortcode can be created by using the `OgImage` class.\n\n```js\nimport { OgImage } from 'eleventy-plugin-og-image/og-image';\n\nconst image = await new OgImage({ inputPath, data, options, templateConfig }).render();\n```\n\n### Capture Output URL\n\nThe plugins shortcode create a `meta` tag per default, modify the `shortcodeOutput` option or class function to directly return the `outputUrl`:\n\n```js\neleventyConfig.addPlugin(EleventyPluginOgImage, {\n  async shortcodeOutput(ogImage) {\n    return ogImage.outputUrl();\n  },\n});\n```\n\nFurthermore, it's possible to capture the `outputUrl` to a variable, e.g. in Nunjucks:\n\n```njk\n{% setAsync \"ogOutputUrl\" -%}\n    {% ogImage \"./og-image.og.njk\", { title: \"Hello World!\" } %}\n{%- endsetAsync %}\n```\n\nAnd use it anywhere afterward with `{{ ogOutputUrl }}`.\n\n## Acknowledgements \u0026 Attributions\n\nThis plugin is deeply inspired by [@vercel/og](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation).\n\nFurthermore, it would not be possible without:\n\n- [satori](https://github.com/vercel/satori)\n- [resvg](https://github.com/RazrFalcon/resvg/)/[resvg-js](https://github.com/yisibl/resvg-js)\n- [sharp](https://github.com/lovell/sharp)\n\n[^1]: Only a subset of HTML elements is [supported by satori](https://github.com/vercel/satori#html-elements).\n\n[^2]: Only a subset of CSS properties are supported by [yoga-layout](https://github.com/facebook/yoga), which is [used by satori](https://github.com/vercel/satori#css).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwikilian%2Feleventy-plugin-og-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwikilian%2Feleventy-plugin-og-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwikilian%2Feleventy-plugin-og-image/lists"}