Never Pet Marmots

    @resoc/eleventy-plugin-social-image

    0.0.4 • Public • Published

    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 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.

    Install

    npm i @resoc/eleventy-plugin-social-image

    DownloadsWeekly Downloads

    1

    Version

    0.0.4

    License

    MIT

    Unpacked Size

    15.3 kB

    Total Files

    8

    Last publish

    Collaborators

    • phbernard