Package: pelican-social-cards
Generate social media cards: A Plugin for PelicanThis plugin generates images with your article titles embedded on them. These images can then be used as "card" metadata and appear on social media when your post is shared, making these posts more visually appealing. The final effect might look something like this:Path to generated image is added to each article / page inog_imageattribute, so it's easy to use in theme.Do note that pluginonlygenerates images - you must reference them in your output HTML for social media platforms to pick them up. There are themes and plugins that can help with that part. See "Referencing file in output HTML" for brief overview of required changes and available options.Generate social media cards: A Plugin for PelicanInstallationUsageInitial configurationPreparing template fileTweaking card visualsFontLine lengthText placement and alignmentControlling text on the cardReferencing file in output HTMLIterating on card designConfiguration optionsSOCIAL_CARDS_TEMPLATESOCIAL_CARDS_PATHSOCIAL_CARDS_FORMAT_EXTENSIONSOCIAL_CARDS_FONT_FILENAMESOCIAL_CARDS_FONT_SIZESOCIAL_CARDS_FONT_FILLSOCIAL_CARDS_FONT_OUTLINE_SIZESOCIAL_CARDS_FONT_OUTLINE_FILLSOCIAL_CARDS_CANVAS_WIDTHSOCIAL_CARDS_CANVAS_HEIGHTSOCIAL_CARDS_CANVAS_LEFTSOCIAL_CARDS_CANVAS_TOPSOCIAL_CARDS_HORIZONTAL_ALIGNMENTSOCIAL_CARDS_VERTICAL_ALIGNMENTSOCIAL_CARDS_LEADINGSOCIAL_CARDS_WRAPPING_FUNCTIONSOCIAL_CARDS_CHARS_PER_LINESOCIAL_CARDS_KEY_NAMESOCIAL_CARDS_INCLUDE_SITEURLSOCIAL_CARDS_INCLUDE_DRAFTSSOCIAL_CARDS_INCLUDE_HIDDENSOCIAL_CARDS_FORCE_SAVEContributingInstallationPlugin can be installed from PyPI:pipinstallpelican-social-cardsUsageInitial configurationFirst, you need an image that will serve as template. For each article, plugin will copy this file and draw text on it. Specify location of this file withSOCIAL_CARDS_TEMPLATEsetting:SOCIAL_CARDS_TEMPLATE = "content/misc/card-template.png"Files will be created insocial-cardssubdirectory of your Pelican content directory (you can change this usingSOCIAL_CARDS_PATHsetting). You should add that directory to yourSTATIC_PATHS, so Pelican can find these images and copy them to output directory.STATIC_PATHS = ['social-cards']That's it! If you build your website now, it will take much longer than usual, as plugin is busy creating all the cards for you. Then, you can see your cards incontent/social-cards/andoutput/static/social-cards/. Don't worry - next build will be about as quick as it has always been, as plugin will not re-create already existing images.If you keep your website in git version control system, you probably want to addsocial-cards/to your.gitignorefile.Read "Tweaking card visuals" for brief overview of settings that you probably want to change, and "Configuration options" for list of all available settings.Preparing template fileEach social media platform has their own requirements towards images associated with shared link. One common element is that card image dimensions should maintain 1.91:1 ratio, or at least approach it. Twitter will accept images as small as 144 x 144 px; Facebook accepts images that are at least 200 x 200 px, but recommends at least 600 x 315 px; LinkedIn expects images to be at least 1200 x 627 px.Overall,1200 x 630 pxis good default size of template image. However, plugin will not enforce any rules on your template, so feel free to use any size you want.What template file represents (how it looks) is entirely up to you. Most social media experts would recommend cards to maintain some relation to visuals of your site. Keeping the same background color and putting your logo / site name somewhere are good starting points. Obviously, you need to leave some empty space, so text doesn't cover other elements of your image.Template file must be in a format that can be read byPillow. JPEG and PNG are good choices.Content ofSOCIAL_CARDS_TEMPLATEsetting is passed verbatim toPIL.Image.open(), which means that you can keep your template file anywhere in your file system. It is recommended to keep it with website sources, probably somewhere incontentorthemedirectory.Tweaking card visualsFontSOCIAL_CARDS_FONT_FILENAMEspecifies font that will be used. Value of this setting is passed verbatim toPIL.ImageFont.truetype(), so all of this function limitations and requirements apply. This should be path to TTF file, or just a name of font file - Pillow will try to find it in global operating system fonts storage.SOCIAL_CARDS_FONT_SIZEspecifies size of the font, in pixels.SOCIAL_CARDS_FONT_FILLspecifies color of text. Value of this setting is passed verbatim toPIL.ImageColor. Pillow supports multiple color formats, but#rrggbborCSS human-friendly nameare probably easiest to use.SOCIAL_CARDS_LEADINGspecifies leading, sometimes also called "line spacing" or "interline spacing", that is the distance from the very bottom of one line of text to the very top of next line. In general, larger font sizes require larger leading.Line lengthSOCIAL_CARDS_CHARS_PER_LINEspecifies the maximum number of characters in one line.textwrap.wrap()is used under the hood, which tries to break lines on last whitespace character before maximum length. This setting is passed aswidthparameter to the function.SOCIAL_CARDS_WRAPPING_FUNCTIONallows you to specify function that will be used instead oftextwrap.wrap. This setting may be useful if you have very specific text wrapping requirements. See also "Controlling text on the card" below.Text placement and alignmentThe area of image where text should be drawn is called "canvas". Plugin does not enforce the text to actually fit that area, but it will issue the warning when text turns out to be larger than designated area. If you experience multiple such warnings, perhaps canvas size, font size or number of characters per line should be adjusted. If you experience only few of these warnings, take a look at "Controlling text on the card" below for setting custom text on per-article basis.SOCIAL_CARDS_CANVAS_WIDTHis width of text area, in pixels.SOCIAL_CARDS_CANVAS_HEIGHTis height of text area, in pixels.SOCIAL_CARDS_CANVAS_LEFTis left margin of text area, that is distance from the left border of image to left border of canvas. Plugin will try to not write any text there, but may fail to do so when your text is not left aligned and line width is larger than canvas width.SOCIAL_CARDS_CANVAS_TOPis top margin of text area, that is distance from the top border of image to top border of canvas. Plugin will try to not write any text there, but may fail to do so when your text is not top aligned and total height of text lines is larger than canvas height.SOCIAL_CARDS_HORIZONTAL_ALIGNMENTis alignment of text within canvas. Valid values are"left","center"and"right". See below for visual representation of various settings.SOCIAL_CARDS_VERTICAL_ALIGNMENTis alignment of text within canvas. Valid values are"top","center"and"bottom". See below for visual representation of various settings.Controlling text on the cardBy default, text written on image will be article / page title. However, you can change that on per-article basis by addingog_image_textcustom metadata to your file header. This may be useful when you want to use shorter version of title on social media card, or when you want finer control on text wrapping without rolling out your own wrapping function.When plugin encountersog_image_textkey, the only thing it does is splitting the value on\ncharacters. No further processing of text is done. That means that you can use\nto force text to wrap to new line; it also means that if you want typographically correct characters (e.g.“”instead of""), you must input them yourself.Referencing file in output HTMLApart from creating image to be used as a card on social media, you must also ensure that social media platforms can find your images. For this, you needog:imagemetadata in head section of your output HTML file:<metaproperty="og:image"content="URL_OF_IMAGE"/>One way of including this HTML is using theme that is aware of open graph tags. Some themes inpelican-themesrepository have support for open graph images built in. To find these themes, clone the repository and use command likegrep -l -R 'og:image'.Another way is usingpelican-seoplugin. That plugin can be used with any theme, as it modifies generated HTML. Support for open graph tags was added in version 1.1.0. To generate open graph tags, you need to setSEO_ENHANCER_OPEN_GRAPHsetting toTrue- however, you need to do that inpelican/plugins/seo/settings.pyfile inside your virtual environment.Iterating on card designGenerating single image may take up to couple hundred milliseconds, so on large sites (few hundred articles) entire process can easily last few minutes. Obviously you don't want to wait so long when you are still trying to find the best settings for your template. Here are two tips on how to approach this problem.One thing you can do is to let plugin generate all the images for you, pick up one that you want to work on and remove it fromcontent/social-cardsdirectory. The next time you build your website, plugin will skip all the images that already exist and generate one missing card. Then you can see how it looks, remove it, adjust the settings and build the website again. Once you are happy with the results, you would remove all the images and allow plugin to generate them again.Another option is to useARTICLE_PATHSPelican setting, which is the list of paths to articles (or directories containing articles) that Pelican should generate. You can set this setting to point to single article, and plugin will generate image only for this article. Once you are happy with the results that you get, remove the setting and generate images for all of your articles.There's alsoPAGE_PATHS, which you can use if your website has more pages than articles.Configuration optionsSOCIAL_CARDS_TEMPLATEPath to image that will serve as template for your cards. For each article, plugin will copy this file and draw text on it.Content of this setting is passed verbatim toPIL.Image.open(), so file must exist and be one of theformats that Pillow can read.This is the only mandatory setting, so leaving it undefined has an effect of disabling the plugin without uninstalling it.Default value:NoneSOCIAL_CARDS_PATHPath to directory where card images will be saved, relative to PelicanPATHsetting. Directory will be created if it doesn't exist.Default value:"social-cards/"SOCIAL_CARDS_FORMAT_EXTENSIONFile extension of generated image. Consequently, this also specifies image format, and must be one of theformats that Pillow can write.Note that while this setting does not have to match format ofSOCIAL_CARDS_TEMPLATEfile, template file must be in the mode supported by the format specified in this setting. Namely, trying to use PNG file with alpha channel as template and JPEG as target format will result in fatal error, as RGBA mode can't be converted to JPEG.JPEG is generally faster to write, but PNG supports alpha, hence latter is the default.Default value:"png"SOCIAL_CARDS_FONT_FILENAMEName of font to use. Value of this setting is passed verbatim toPIL.ImageFont.truetype(), so all of this function limitations and requirements apply. This should be path to TTF file, or just a name of font file - Pillow will try to find it in global operating system fonts storage.Default value:"Arial.ttf"SOCIAL_CARDS_FONT_SIZESize of font, in pixels.Default value:70SOCIAL_CARDS_FONT_FILLColor of text. Value of this setting is passed verbatim toPIL.ImageColor. Pillow supports multiple color formats, but#rrggbbandCSS human-friendly nameare probably easiest to use.Default value:"#000000"SOCIAL_CARDS_FONT_OUTLINE_SIZEWidth of font outline, in pixels. This effect as also known as "text stroke", and results in text being surrounded by a line of potentially different color (seeexample image). Value of this setting is passed verbatim to Pillow.Value of0results in no outline being drawn.Default value:0SOCIAL_CARDS_FONT_OUTLINE_FILLColor of font outline. Value of this setting is passed verbatim toPIL.ImageColor. Pillow supports multiple color formats, but#rrggbbandCSS human-friendly nameare probably easiest to use.This setting only takes effect whenSOCIAL_CARDS_FONT_OUTLINE_SIZEis set to a positive integer.Default value:"#000000"SOCIAL_CARDS_CANVAS_WIDTHWidth of "canvas" in pixels. Canvas is special area where text will be drawn. Depending on font style, font size and number of characters in the line, text may actually be drawn outside of this area - but plugin will issue a warning in this case.Default value:1200SOCIAL_CARDS_CANVAS_HEIGHTHeight of "canvas" in pixels. Canvas is special area where text will be drawn. Depending on font size, leading and number of lines, text may actually be drawn outside of this area - but plugin will issue a warning in this case.Default value:630SOCIAL_CARDS_CANVAS_LEFTDistance from the left border of image to left border of canvas (left margin of canvas). Plugin will try to not write any text there, but may fail to do so when your text is not left aligned and line width is larger than canvas width.Default value:0SOCIAL_CARDS_CANVAS_TOPDistance from the top border of image to top border of canvas (top margin of canvas). Plugin will try to not write any text there, but may fail to do so when your text is not top aligned and total height of text lines is larger than canvas height.Default value:0SOCIAL_CARDS_HORIZONTAL_ALIGNMENTAlignment of text within canvas. Valid values are"left","center"and"right". See "Text placement and alignment" above for visual representation of various settings.Default value:"center"SOCIAL_CARDS_VERTICAL_ALIGNMENTAlignment of text within canvas. Valid values are"top","center"and"bottom". See "Text placement and alignment" above for visual representation of various settings.Default value:"center"SOCIAL_CARDS_LEADINGDistance from the very bottom of one line of text to the very top of next line, in pixels.Leadingis term from typography that is subject to confusion from various DTP software vendors, and sometimes is called "line spacing" or "interline spacing".Default value:15SOCIAL_CARDS_WRAPPING_FUNCTIONFunction used to wrap text, that is to turn long string into list of shorter strings. Article / page title will be passed through it before being drawn on the image. Note that this must be actual Python function, andnotthe name of the function as a string.This function will be used in place oftextwrap.wrap, so it must maintain the same interface. Namely, it must accept single positional argument,text(string to work on), and single keyword argument,width(maximum number of characters per line).SOCIAL_CARDS_CHARS_PER_LINEsetting value will be passed aswidthargument. Function must return list of strings, each element being a line of text to draw,withoutnew line character at the end.Default value:textwrap.wrapSOCIAL_CARDS_CHARS_PER_LINEMaximum number of characters in one line. This value will be passed toSOCIAL_CARDS_WRAPPING_FUNCTIONfunction aswidthkeyword argument.SOCIAL_CARDS_WRAPPING_FUNCTIONdefaults totextwrap.wrap().Default value:30SOCIAL_CARDS_KEY_NAMEName of article / page attribute that will contain path to generated image (relative to Pelican settingOUTPUT_PATH).Open graph metadata was never part of Pelican's standard set of content metadata, so various themes and plugins authors had different ideas how that data should be specified.og_imageseems to be the most popular option by wide margin, but some authors decided to usefeatured_image,imageorheader_cover. If you happen to use theme that uses one of these attributes, this setting allows you to use plugin without changing the theme.Do note that this value also impactsog_image_textattribute, described in "Controlling text on the card" section above. In fact, plugin will look intof"{SOCIAL_CARDS_KEY_NAME}_text"attribute before using article title as source of text to draw. So if you change this setting to"featured_image", overriding text on per-article basis will be done throughfeatured_image_textkey.Default value:"og_image"SOCIAL_CARDS_INCLUDE_SERIESIfTrue, article series name will be included before title in text written on the card.Series name is defined by "Series" metadata key, as understood bypelican-series plugin.Note that series name inclusion will work also when you do not have series plugin installed. Set this toFalseif your post titles already have series identifier.Default value:FalseSOCIAL_CARDS_SERIES_FORMATString template for article series name.Pythonformat()method will be called on this string, with series name as the only parameter.{}will be replaced by series name. Use{{for literal{and}}for literal}. If you want to surround series name with curly brackets, set this to{{{}}}.Default value:"{}: "SOCIAL_CARDS_INCLUDE_SITEURLIfTrue, path to generated image (article / pageog_imageattribute) will includeSITEURLsetting value at the start.Open graph metadata was never part of Pelican's standard set of content metadata, so various themes and plugins authors had different ideas if per-postog_imagemetadata should be path relative to built website root, or fully-specified URL. Relative path seems to be more popular choice. However, if you happen to use theme that expectsog_imageattribute to be fully-specified URL, this setting allows you to use plugin without changing the theme.Default value:FalseSOCIAL_CARDS_INCLUDE_DRAFTSGenerate card images also for draft articles and pages.Default value:FalseSOCIAL_CARDS_INCLUDE_HIDDENGenerate card images also for hidden pages.Default value:FalseSOCIAL_CARDS_FORCE_SAVEPlugin will skip generating image if file with the same name already exists. With this setting, you can change that behavior. This setting is mostly useful for debugging purposes, but might also be used when you changeSOCIAL_CARDS_TEMPLATEvalue and it's easier for you to change setting than remove existing images, or when you use your computer for heating and need to maintain high CPU load.Default value:FalseContributingContributions are welcome and much appreciated. Every little bit helps. You can contribute by reporting problems you have encountered, by improving this documentation, and by submitting code changes.We mostly follow general Pelican guidelines, so you can start with review of theContributing to Pelicandocumentation, beginning with theContributing Codesection.