plugin-cards (A README Experience)

A Micro.blog plugin for adding Twitter and Open Graph <meta> tags, which are used to generate link preview cards all over the [email protected] 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. Its code lives here.

Twitter / Open Graph Cards

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

Audo Card

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 <meta> tags into the page <head>. 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 (shown split across multiple lines in invalid CSS syntax for clarity) 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

Generated Card Preview

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:

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: https://moondeer.blog/gallery/

I get a Twitter card like this:

Gallery Card

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

Then I get a Twitter card like this:

Perspectives Card