@resoc/eleventy-plugin-social-image

Resoc Social Image plugin for 11ty

Create automated social images for your 11ty website.

At the moment, this plugin works only for 11ty sites deployed to Netlify.

How it works:

• Create a Resoc social image template, with HTML & CSS.
• Install and configure this plugin, along with the Resoc social image Netlify build plugin.
• In the 11ty website (probably in the base template), pass parameters to the image template.
• At runtime, the social images are generated by a Netlify function, using an on-demand builder.

Create an image template

Create a template:

cd my-11ty-project
npx itdk init resoc-templates/default -m title-description

This command generates a template files in resoc-templates/default and launch a viewer in a browser. The template expects two parameters: a title and a description. We can change them or add new ones.

To learn more, visit the Image Template Dev Kit.

Install the plugins

We are going to install two plugins:

• @resoc/eleventy-plugin-social-image (this plugin)
• @resoc/netlify-plugin-social-image, which will setup a Netlify function, in charge of generating the social images

Install the packages:

npm install --save-dev @resoc/eleventy-plugin-social-image @resoc/netlify-plugin-social-image

In .eleventy.js, add the plugin:

const pluginResoc = require("@resoc/eleventy-plugin-social-image");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(pluginResoc, {
    // The directory of the Resoc templates
    templatesDir: 'resoc-templates',

    // The path when social images will be served, eg. /social-images/homepage.jpg
    openGraphBasePath: '/social-images',

    // A file which maps pages to templates and parameters
    slugToImageDataMappingFile: 'resoc-image-data.json',

    // Ask the plugin to configure netlify.toml accordingly
    patchNetlifyToml: true
  });
};

The plugin always makes sure the Netlify plugin is correctly configured in netlify.toml. When is it not:

• patchNetlifyToml set to false (default): the plugin fails and explains what to do to fix the error.
• patchNetlifyToml set to true: the plugin updates netlify.toml. When it happens, comments and formatting are lost. If your file is simple, this might be perfectly fine. If your file is complex and with comments, you don't want the plugin to touch it.

If you don't use patchNetlifyToml, in netlify.toml, declare the Netlify build plugin:

[[plugins]]
package = "@resoc/netlify-plugin-social-image"
  [plugins.inputs]
  templates_dir = "resoc-templates"
  open_graph_base_path = "/social-images"
  slug_to_image_data_mapping_file = "resoc-image-data.json"

The various inputs (templates_dir, etc.) must match what your declared in .eleventy.js as parameters or the 11ty plugin. If we don't do so, the 11ty plugin detects it and explains what to do.

Invoke the social images

Suppose we have a master layout in _includes/layouts/base.njk.

Near the top of the file, declare a variable socialImage:

{% set socialImage %}
{%- resoc
      template = "default",
      slug = (title or metadata.title) | slug,
      values = {
        title: title or metadata.title,
        description: description or metadata.description
      }
-%}
{% endset %}

The template is default. Because we set templatesDir to resoc-templates earlier as a plugin parameter, it means a template should exist in resoc-templates/default. This is the case, since we called npx itdk init resoc-templates/default.

The slug must be unique. It can be a slugified version of the page title, an identifier, etc.

The values will be fed as the template parameters.

Still in _includes/layouts/base.njk, head section, declare the Open Graph image:

<meta name="og:image" content="{{ socialImage }}"/>

Deploy

At build time, a mapping file is created (which name is set via the plugin parameter slugToImageDataMappingFile). It is filled with the information provided to the resoc short code.

When the project is deployed to Netlify, this file is generated. The Netlify plugin creates a Netlify function which uses this file to generate the images.