Wondering what’s next for npm?Check out our public roadmap! »

    eleventy-plugin-social-share-card-generator

    1.0.6 • Public • Published

    Social Share Card Generator

    This plugin helps you to build automatic social share cards for your 11ty project. The underlying functionality is enabled by Cloudinary, a cloud based image management, optimisation and transformation solution.

    Preparation

    To enable the social share card generator to function propertly a Cloudinary account is required. You can register for free here, it takes less than 30 seconds. After registration please either copy your cloud-name or update your cloud-name and save it/remember it because you'll need it later.

    Setup

    To install the plugin you need to run npm i eleventy-plugin-social-share-card-generator.

    Getting started

    The plugin will enable you to create social share cards in an automated way by overlaying text on a pre-defined background image. That image needs to be uploaded to Cloudinary first. The easiest way would be for you to login to your Cloudinary account, click the Media Library menu and drag your image for upload. If you don't have a suitable background ready, you'd need to create one. Should you not have access to a tool like Photoshop you can use an online editor such as Pixlr.

    If you'd like to learn how to create a social share background please consult this article by Jason Lengstorf

    Note that ideally a social share base image should be 1200 x 630 pixels in size.

    After uploading the file take a note of the public ID (the unique identifier of the image in Cloudinary).

    Once you have done these steps, you can add the plugin to your .eleventy.js configuration file, making sure to update the YOUR-CLOUDINARY-USERNAME and YOUR-PUBLIC-ID values.

    const socialShareCardGenerator = require('eleventy-plugin-social-share-card-generator/dist/lib');
    module.exports = (eleventyConfig) => {
      eleventyConfig.addPlugin(socialShareCardGenerator, {
        cloudName: 'YOUR-CLOUDINARY-USERNAME',
        publicId: 'YOUR-PUBLIC-ID',
      });
    };

    It is recommended that you setup the cloudName and publicId when initialising the plugin. Additional defaults can be setup as well upon initialisation, details of these can be found below.

    Configuration

    There are a vast number of options that you can configure using the plugin - some configuration options can be done from .eleventy.js and some from the template files. Find a list of possible configuration options below.

    Note that in the above table the init column refers to values that can be set via .eleventy.js while the template column refers to values that can be set from the templating language.

    Option Set it via Default Value init template data type values
    Cloud Name cloudName no default X X string any
    Public ID publicId no default X X string any
    Font Colour fontColour eee X X string any Hex value (without the # symbol)
    Font Face fontFace Roboto X X string any Google Font
    Font Line Spacing fontLineSpacing -10 X X number any
    Font Size fontSize 70 X X number any
    Font Weight fontWeight semibold X X string any per Google Font
    Text Position on Overlay position west X X string north_east, north, north_west, west, south_west, south, south_east, east, center
    Text Position on X axis x X X number any
    Text Position on Y axis y X X number any
    Overlay Text overlayText no default X string any

    Note that the overlayText can only be set from the template.

    A note on font support

    Generally speaking, Cloudinary supports all of Google's Fonts. However, there could be some fonts that are not supported - please make sure to test your social share card.

    Overlays

    The options are created in a way that they can be overwritten after initalisation from the templating language as well (except for the overlayText).

    Template usage

    Using Nunjucks, you can set the overlayText and assign the result from the social share card generator to a variable using the following code:

    {% set img %}
    {% sscg overlayText = "Hello there" %}
    {% endset %}
    
    <img src={{img}} alt="Social Share Card Test Preview" />

    As you can see the plugin enables the usage of sscg in your template. Additional value can be set using sscg, which will overwrite your defaults created via the initialisation step in .eleventy.js, for example:

    {% set img %}
    {% sscg overlayText = "Hello there",
    fontFace = 'Sacramento',
    fontWeight = 'normal' %}
    {% endset %}
    
    <img src={{img}} alt="Social Share Card Test Preview" />

    For best results, you can automate the creation of a social share card for your blog. This is possible via plugins for 11ty that generate meta elements, such as metagen. Using the below strategy you will be able to take the title of your blogpost and inject that dynamically as an overlay to the social share card plugin.

    // .eleventy.js
    const metagen = require('eleventy-plugin-metagen');
    const socialShareCardGenerator = require('eleventy-plugin-social-share-card-generator/dist/lib');
    
    module.exports = function (eleventyConfig) {
      eleventyConfig.addPlugin(metagen);
      eleventyConfig.addPlugin(socialShareCardGenerator, {
        cloudName: 'YOUR-CLOUDINARY-USERNAME',
        publicId: 'YOUR-PUBLIC-ID',
      });
    };
    ---
    title: 'Hello World - this is my first article'
    desc: 'Meta Description'
    twitter: '@tpiros'
    name: 'Tamas Piros'
    ---
    <!DOCTYPE html>
    
    <html lang="en">
      <head>
        <meta charset="utf-8"/>
        <title>Test</title>
        {% set img %}
        {% sscg overlayText = title %}
        {% endset %}
    
        {% metagen name = name,
        title = title,
        desc = excerpt,
        twitter_card_type = "summary_large_image",
        url = page.url,
        twitter_handle = twitter,
        img = img %}
      </head>
    
      <body>
        {{ content | safe }}
      </body>
    </html>

    Sample

    Take a look at the sample folder for an example implementation. After running npm i in that folder, please go ahead and add your own Cloudinary username and the publicId of your base image (the background image). Once done, you can run npx @11ty/eleventy --serve to view the result in your browser.

    Install

    npm i eleventy-plugin-social-share-card-generator

    DownloadsWeekly Downloads

    5

    Version

    1.0.6

    License

    ISC

    Unpacked Size

    13.7 kB

    Total Files

    9

    Last publish

    Collaborators

    • avatar