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 tosite.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 tosite.Author.name
orsite.Params.Author.name
when empty. - ProfileURL
- The value to set for
author.url
within the JSON object. Defaults tosite.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 thecardify.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 theCard.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:
and aReadMoreLink = '.read-more' ListSandbox = '.post-body' PageSandbox = '#post-body'
site.BaseURL
equal tohttps://My.blog
the default value of the host match selector would be:
Setting this value to a non-empty string will completely replace the default selector with the custom selector value.#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"])
- 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 is1rem
. - SpacerX
- Horizontal padding applied to
.cardify-card-body
. Default is1rem
. - TitleSpacerY
- Bottom margin applied to
.cardify-card-title
. Default is `1rem * 0.5`. - BG
- Background color applied to
.cardify-card
. Default iswhite
. - BorderWidth
- Width value for the border applied to
.cardify-card
. Default is1px
. - BorderColor
- Color value for the border applied to
.cardify-card
. Default is `rgba(black, .125)`. - BorderRadius
-
border-radius
value for.cardify-card
. Default is0.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 istrue
. - SassOutput
- Output style for
/assets/sass/cardify.scss
. Valid options arenested
,expanded
,compact
andcompressed
. Default iscompressed
. - MinfiyScript
- Whether to minify the Javascript file generated from
/assets/js/cardify.js
. Default istrue
.
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: