Introduction & Installation

Social Media Image Kit is a Statamic 4 addon that provides a framework for easily generating social media images for your site's content. Images are created by rendering Antlers or Blade templates and converting the results to an image.

Generated images will be stored within an asset container, and automatically linked to your site's entries based on the social media platforms you have configured.

Installing Social Media Image Kit can be broken up into four different phases:

1. Installation: Installing the required composer packages, and ensuring the configuration and assets have been published to the local project.

2. HTML Rendering Setup: Configuring the local environment for Browershot and Puppeteer.

3. Creating the Asset Container: Creating the asset container where generated social media images will be stored.

4. Configuring Collections and Blueprints: Specifying which collections will have images generated and adding the required fieldset to their blueprints.

#Installation

Social Media Image Kit can be installed into an existing Statamic project by running the following command from the root of your project:

1composer require stillat/social-media-image-kit

Social Media Image Kit requires some configuration and front-end assets to be available within your project in order to work correctly. To ensure these are available, you may run the following command after installing the composer package:

1php artisan vendor:publish --tag=social-media-image-kit

To publish the configuration files, please run the following command from the root of your project:

1php artisan vendor:publish --tag=social-media-image-kit-config

#HTML Rendering Setup

If you intend to use the provided Browershot, you will also need to ensure that Puppeteer is installed and configured on your system. For more information on how to do this, please consult the Browsershot documentation at https://spatie.be/docs/browsershot/v2/requirements.

Each environment is different and may pose its own unique challenges when installing or configuring Puppeteer. Because of the high degree of variability, if you are experiencing problems, it is recommended to search online to help locate resources to resolve your issue.

As a starting point, here is a list of great resources:

• Browserhot Installation Requirements

• Puppeteer Troubleshooting Documentation

If you are working to install Puppeteer on WSL, ensure that you are running WSL version 2.

#Creating the Asset Container

Before continuing with the rest of the documentation, we need to create an asset container to work with. Social Media Image Kit is configured to use an asset container with the handle social_media_images by default. If you do not already have an asset container with this handle, it is recommended to stick with the defaults.

To have Social Media Image Kit create the asset container automatically, you may run the following command from the root of your project:

1php artisan social-media-image-kit:install-asset-container

If you need to customize the asset container's handle because you already have a conflicting asset container, be sure to update the asset_container configuration value within general.php before running the command:

 1<?php
 2 
 3return [
 4 
 5    // ...
 6 
 7    /*
 8    |--------------------------------------------------------------------------
 9    | Asset Container
10    |--------------------------------------------------------------------------
11    |
12    | This option defines the Statamic asset container utilized by the Social
13    | Media Image Kit for image storage. Once this option is set, it should
14    | not be changed. Doing so may result in broken images for entries.
15    |
16    */
17 
18    'asset_container' => 'social_media_images',
19 
20    // ...
21];

#Configuring Collections and Blueprints

Social Media Image Kit needs to know which collections to generate social media images for. This is done within the general.php configuration file:

 1<?php
 2 
 3return [
 4 
 5    // ...
 6 
 7    /*
 8    |--------------------------------------------------------------------------
 9    | Collection Handles for Image Generation
10    |--------------------------------------------------------------------------
11    |
12    | The 'collections' array specifies which collection handles the Social Media
13    | Image Kit addon will reference to retrieve entries. Only collections that
14    | appear in this array will be used to generate social media images for.
15    |
16    */
17 
18    'collections' => [
19        'documentation',
20        'pages',
21    ],
22 
23];

To add collections we need to add the collection's handle to the list of collections within the configuration file. Each configured collection will also need to import Social Media Image Kit's fieldset into its blueprint.

This blueprint contains important fields that help with the automated management of generated images, as well as providing the option for content editors or site administrators to specify a custom image on a per-entry basis.

You can view the bundled fieldset within the Control Panel by navigating to the "Fieldsets" page:

When importing the fieldset into your existing blueprints, it is recommended that you do not prefix the fieldset. If you have a common fieldset, such as "SEO" or "Metadata" that is included on each page, you may simply add the Social Media Images fieldset to that.

Social Media Image Kit will only generate images for those collections specified within the configuration file, even if other collections contain the imported fieldset.