Plugin-cards version 4, adds structured data and preview card generation for links inside posts and post-lists

Moondeer · November 30, 2021, 12:36am

plugin-cards

A Micro.blog plugin for adding Twitter and Open Graph <meta> tags, which are used to generate link preview cards all over the g0dd@mn place. As of version 4, the plugin will also generate structured data for posts, which is utilized by search engines. The plugin can also generate card previews of its own to drop into your blog.

Open Graph audio meta tags are created when an audio file is detected.

Plugin Parameters

The plugin parameters are grouped by the functionality they target. They are all reachable from the plugin parameters interface, however, I am going to describe them using the logic they hold in the template data file (which may be used as an alternative to the plugin parameter interface) that lives at /data/plugin_cards/config.toml.

TwitterOG

Twitter and Open Graph Parameters

Enable: Whether to inject Twitter and Open Graph tags into the page . The default value is true.
TwitterUsername: Username for Twitter <meta> tags. Defaults to site.Params.twitter_username when empty.

StructuredData

Structured Data Parameters

Enable: Whether to inject an application/ld+json script in the page <head> with structured data for search engines
AuthorName: The value to set for author.name within the JSON object. Defaults to site.Author.name or site.Params.Author.name when empty.
ProfileURL: The value to set for author.url within the JSON object. Defaults to site.Author.profileurl when empty.

Card.Creation

Preview Card Creation Parameters

QueryMatch: Whether to replace links ending with *cardify* with a preview card generated by scraping the linked page for Twitter / Open Graph tags. When set to true, a link like <a href="https://my.blog/2021/11/29/my-post.html?cardify">whatever</a> would be replaced with a preview card by the cardify.js script.
HostMatch: Whether to automatically replace any link for a site page with a preview card generated by scraping the linked page for Twitter / Open Graph tags. Exactly which links are replaced withcards may be controlled via the Card.HostMatch parameters. When set to true, a link like <a href="https://my.blog/2021/11/29/my-post.html>whatever</a> may be eligible for preview card replacement depending on how the Card.HostMatch parameters have been configured.

Card.HostMatch

Parameters for preview cards created automatically when the link points to another page of the Hugo generated site.

ReadMoreLink

A CSS selector specifying the links used by post summaries. This is used to exclude such links from generating preview cards. Default is .read-more.

ListSandbox

A CSS selector that leads right up to the <a> tags that should be eligible for automatic replacement in post lists. This becomes part of the final host match selector. Default is .post-body.

PageSandbox

A CSS selector that leads right up to the <a> tags that should be eligible for automatic replacement in post pages. This becomes part of the final host match selector. Default is #post-body.

CustomSelector

A custom CSS selector to use in place of the that which would be generated using the three parameter values above. Given the default values:

ReadMoreLink = '.read-more'
ListSandbox = '.post-body'
PageSandbox = '#post-body'

and a site.BaseURL equal to https://My.blog the default value of the host match selector would be:

#post-body a[href*="My.blog"]:not(.cardify-card-link):not([href$="cardify"]),
#post-body a[href*="my.blog"]:not(.cardify-card-link):not([href$="cardify"]),
.post-body a[href*="My.blog"]:not(.read-more):not(.cardify-card-link):not([href$="cardify"]),
.post-body a[href*="my.blog"]:not(.read-more):not(.cardify-card-link):not([href$="cardify"])

Setting this value to a non-empty string will completely replace the default selector with the custom selector value.

URLFilter

A regular expression for whitelisting which links are eligible for automatic replacement. This is applied on top of the CSS selection. The default value, .*.html, excludes category pages, for example.

Card.Style

Parameters for styling preview cards

SpacerY: Vertical padding applied to .cardify-card-body. Default is 1rem.
SpacerX: Horizontal padding applied to .cardify-card-body. Default is 1rem.
TitleSpacerY: Bottom margin applied to .cardify-card-title. Default is `1rem * 0.5`.
BG: Background color applied to .cardify-card. Default is white.
BorderWidth: Width value for the border applied to .cardify-card. Default is 1px.
BorderColor: Color value for the border applied to .cardify-card. Default is `rgba(black, .125)`.
BorderRadius: border-radius value for .cardify-card. Default is 0.5rem.
TimeDateColor: Color applied to the last .cardify-card-text element (containing the publish date and estimated reading time). Default is #666666

Build

Parameters for controlling the generated css and js files

Fingerprint: Whether to provide subresource integrity by generating a base64-encoded cryptographic hash and attaching a .Data.Integrity property containing an integrity string, which is made up of the name of the hash function, one hyphen and the base64-encoded hash sum. Default is true.
SassOutput: Output style for /assets/sass/cardify.scss. Valid options are nested, expanded, compact and compressed. Default is compressed.
MinfiyScript: Whether to minify the Javascript file generated from /assets/js/cardify.js. Default is true.

Card Data

The Card Data parameter is optional. I highly recommend using the data template provided at /data/plugin_cards/data.toml or creating a template in your custom theme at /data/plugin_cards_data.toml as an alternative to storying a stringified version of the data via the plugin paramters interface. All three locations are acceptable. The next section discusses how the entries are used to provide images for Twitter / Open Graph cards for pages without an image.

Card Image

The first image found gets priority. The large summary Twitter card will be generated when there is an image available; otherwise, the smaller summary card is generated.

When the page for which you are generating cards does not have an image available in its front matter, that’s when cool sh$t happens … and why that Card Data parameter is there.

The data consists of a JSON object stored as a string (which is what happens when you paste your JSON object code into the field and hit the button). The pasted code might look something like this:

{
  "default": "https://moondeer.blog/uploads/2021/7c412827ad.jpg",
  "/plausible/": "https://moondeer.blog/uploads/2021/e71e7d47c1.jpg",
  "/2021/": "https://moondeer.blog/uploads/2021/98295e13a8.jpg",
  "/2020/": "https://moondeer.blog/uploads/2021/24760a1062.jpg",
  "/about/": "https://moondeer.blog/uploads/2021/955619b235.jpg",
  "/cloud/": "https://moondeer.blog/uploads/2021/547d825d8a.jpg",
  "/bookshelf/": "https://moondeer.blog/uploads/2021/27a279361f.jpg",
  "/gallery/":"https://moondeer.blog/uploads/2021/8585a4a081.jpg",
  "/categories/perspectives/": "https://moondeer.blog/uploads/2021/f5f64b49bb.jpg",
  "/categories/projects/": "https://moondeer.blog/uploads/2021/a0c8728c89.jpg",
  "/categories/poetry/": "https://moondeer.blog/uploads/2021/23a2035cdc.jpg",
  "/categories/music/": "https://moondeer.blog/uploads/2021/8d0a055caa.jpg",
  "/categories/programming/": "https://moondeer.blog/uploads/2021/47e02e5e74.jpg",
  "/categories/critters/": "https://moondeer.blog/uploads/2021/0a37500db6.jpg",
  "/categories/stream-of-consciousness/": "https://moondeer.blog/uploads/2021/c11b3de2ff.jpg",
  "/categories/inside-the-art/": "https://moondeer.blog/uploads/2021/8c4669346c.jpg",
  "/categories/biographical-tripe/": "https://moondeer.blog/uploads/2021/92a565154b.jpg",
  "/categories/artsy-fartsy/": "https://moondeer.blog/uploads/2021/76f1f5d0d6.jpg",
  "/categories/personal-favorites/": "https://moondeer.blog/uploads/2021/328c442bd6.jpg"
}

All the values are image URLs. As for the keys, there are really only two things happening here. There is a default entry, which is used whenever nothing else could be retrieved. All the remaining keys are site paths. The bits that follow [SCHEME://HOSTNAME]. This is how your pages without images in the front matter get their image card.

Starting with version 2, instead of pasting all that JSON into the parameter field, you can save it into a template file located at data/plugin_cards/card_data.json.

Soooo … when I leave a link like this: On the Mind of Moondeer - Gallery

I get a Twitter card like this:

Orrrr … say I leave a link like this: https://moondeer.blog/perspectives/

Then I get a Twitter card like this: