Automatic social media card generator for Sphinx

[choldgraf]

Many websites nowadays are adding the ability to dynamically generate large social media previews for the site. This boosts visibility and creates a professional look that is easier to quickly glance at. Here are a few examples:

GitHub

MkDocs Material

@jacobtomlinson 's blog

Usually, these are generated dynamically by a server when a page request is made, but I think that we could get this working statically by generating the images for each page at build time.

Idea

I think you could accomplish this via a Sphinx extension that did the following things:

• Grabbed the page's title and maybe some metadata from the book defined in conf.py
• Defined some CSS rules that were triggered with a @media query that was for the exact size of the social media card. These styles would just grab the elements we want in the image preview, and style/position them absolutely to look nice.
• Used the playwrite python package to simulate a chromium browser at the size needed for social image cards, and generate a screenshot
• Do this for each page in the documentation and add it to a folder in _static
• Add a meta tag for the og:image that pointed to this static image

[choldgraf]

Update: the sphinxext.opengraph folks are interested in having this functionality in their package. Here's the issue to track that:

• Auto-generate page preview images based on page metadata wpilibsuite/sphinxext-opengraph#66

[2bndy5]

I'm working on a new sphinx extension that mimics the mkdocs-material theme's builtin social plugin which supports (via insider's edition recent overhaul) customizable layouts. I have the customizable layouts (yaml-based jinja templates) working, but they could be improved for template inheritance (which is also working). I'm using pillow with SVG support via ImageMagick CLI. Fonts are fetched from fontsource API.

2bndy5/sphinx-social-cards; This feels like unintentional spam, but it is related to this topic 😃

My gripes about sphinxext-opengraph

1. It is too rigid for what I had envisioned. The font is hard-coded. The layout uses a "one-size-fits-all" paradigm aside from changing the images used and the color of the bottom stripe.

2. It uses matplotlib. I chose to go with pillow because I can dynamically validate/adjust font sizes and colors (and conditionally mask images with a fill color) as needed when generating the cards. Additionally, the matplotlib docs recommends using pillow to open images, so I figured it was an unnecessary dependency in my extension.

3. You can't (easily) disable the generation for a specific page. I'm adding a directive that could be used to override a card's layout for a specific page and/or explicitly invoke the card generation when it is globally disabled in conf.py. I'm also using this directive to dynamically generate examples in my extension's docs. As I developed this directive, it became clear that a derivative of the directive can be used as an alternative to the rST image directive...

4. As an implementation note, sphinxext-opengraph requires that the sphinx theme inherits from (and uses) the sphinx basic theme's HTML template to inject the required metadata. This is not always the case as the sphinx docs note that inheriting from the basic theme is entirely optional. The sphinx-immaterial theme does not use the basic theme's templates, so users can't utilize the sphixext-opengraph extension with that theme. 😞

   Instead, I use a SphinxTransform to inject docutils.nodes.meta nodes into the document's doctree; the above mentioned directive injects these nodes as the document is read. No existing metadata is overwritten or removed, but existing metadata is used to alter the card's content where applicable.