npm package: @resoc/eleventy-plugin-social-image
Description: Generate social images at runtime
Author: Philippe Bernard
Latest version: 0.0.4

# 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](https://www.npmjs.com/package/itdk),
with HTML & CSS.
- Install and configure this plugin, along with the [Resoc social image Netlify build plugin](https://www.npmjs.com/package/@resoc/netlify-plugin-social-image).
- 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](https://www.netlify.com/products/functions/), using an [on-demand builder](https://docs.netlify.com/configure-builds/on-demand-builders/).

## Create an image template

Create a template:

```bash
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](https://www.npmjs.com/package/itdk).

## 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:

```bash
npm install --save-dev @resoc/eleventy-plugin-social-image @resoc/netlify-plugin-social-image
```

In `.eleventy.js`, add the plugin:

```javascript
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:

```toml
[[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`:

```njk
{% 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:

```html
<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.