Duncan McClean

Social Shots Documentation

Duncan McClean


Social Shots provides its own configuration file. You can use this to configure the collections/entries you'd like to generate social images for.

You'll need to specify the collection, the blueprint (or provide a wildcard, like *). Inside that array you may configure the field handle (like og_image or twitter_image in the below example) and the 'image type' (either open_graph or twitter).

In the configuration file, you may also specify the asset container you wish to store your generated social images in.

return [

    'collections' => [
        'pages' => [ // collection handle
            'page' => [ // blueprint handle
                'og_image' => 'open_graph', // field handle => 'open_graph' or 'twitter'
                'twitter_image' => 'twitter',

    'storage' => [
        'container' => 'assets',
        'directory' => 'social-images',


After updating the config, you may want to re-generate (or 'warm') your social images. You can do this with the php please social-shots:warm command.


After you've installed and configured Social Shots, it will automatically generate the configured images whenever entries are saved.

Hot tip: to work around slow-saving in the Control Panel, you should use a different queue driver (eg. not sync). There's a breif mention of queue drivers in the Git integration docs which may be useful.

If you want to generate your social images on demand, you may use the php please social-shots:warm command which will loop through all your entries and generate social images for them. Depending on your number of entries, this may take a while.


Probably the biggest selling point (or free-ing point, as this addon is free - see what I did there) for this addon is that you can build your own social images with HTML, CSS & Antlers. The best combination in web history.

In your social image template, you can use any of the variables that would be normally available to you, as if you were in the entry's native template. Here's a really simple example:

<!DOCTYPE html>
        <!-- TailwindCSS for the win! -->
    <body class="bg-white bg-pattern flex flex-col items-center justify-center">
        <div class="w-4/5 mx-auto bg-white p-8">
            <h2 class="text-3xl text-center font-semibold text-gray-800 mb-4">{{ title }}</h2>
            <h2 class="text-sm text-center font-medium text-gray-800">Published on {{ date }}.</h2>

View Conventions

Social Shots will expect that your views live in a certain folder & naming structure. This is likley something that will be loosened in future versions but as of right now, it's pretty fixed.

Social Shots will work down this list in order. If it can't find one view, it'll try the next and so on. Until it can find one that exists.

  • social_shots.{collection_handle}.{blueprint}.{imageType}
  • social_shots.{collection_handle}.{blueprint}.
  • social_shots.{collection_handle}.{imageType}
  • social_shots.{collection_handle}
  • social_shots.default
  • social_shot