Sharing cards

What a shared link shows, and the sharing card, a picture Statac can draw for each page from its own words.

What a link preview shows

The site or app a link is pasted into makes the preview from these tags in the page’s <head>.

page.og_title is the page’s og_title, or else what headline(page) calls it. In a page’s front matter, for a title too long for a card:

title: A title with more words in it than a card has room to draw
og_title: A shorter title

Turn cards on

statac new --cards

Run it in the site’s folder, or give it the folder. It writes the card’s six files:

From the next build, a card is drawn for each page but the 404 page, once the site has an address. Given a folder that is empty or isn’t there, it makes the new site with its card from the start.

It never writes over a file of yours:

`templates/og.yaml` is yours and wasn't touched.

Where one of the card’s other files is missing, statac new --update --missing writes it: see bring the starter up to date.

To turn cards off, remove templates/og.yaml.

Put the card in a layout

A new site’s templates/base.html already asks for the card. In the <head> of a layout of your own:

{% if page.card is defined %}
<meta property="og:image" content="{{ page.card.url | absolute }}">
{% if page.card.width %}
<meta property="og:image:width" content="{{ page.card.width }}">
<meta property="og:image:height" content="{{ page.card.height }}">
{% endif %}
<meta property="og:image:alt" content="{{ page.card.alt }}">
<meta name="twitter:card" content="summary_large_image">
{% endif %}

Statac draws a card only for a page whose layout reads page.card. A page with no card has no page.card, so the layout asks first.

absolute writes the address whole, with the site’s url, as a preview needs it. page.card is read in a layout, or in a snippet a layout calls.

The card’s settings

In templates/og.yaml:

background: background.png
font: [text.ttf, more.ttf]
padding: 70

title.text: "{{ page.og_title }}"
title.place: centre
title.size: up to 75
title.colour: "#F2E9D3"

footer.text: "{{ site.title }}"
footer.place: bottom
footer.size: 36
footer.colour: "{{ page.accent | default('#B9A88F') }}"

Every other line belongs to a text you name, as title or footer, and each text needs all four of its lines. Texts are drawn in the order written.

• A colour starting # goes in quotes, or YAML reads it as a comment.
• Files stay in templates/og/, in a folder inside it if you like, as fonts/text.ttf.

A text is built for each page as a template is, with page the page the card is for. For a text or a colour some pages leave empty, give a default: {{ page.summary | default("") }}. What it builds is drawn as it stands, never read as markup.

Where texts go, and how large

Texts sharing a place stack in the order written. Each wraps within the width inside the padding, lined up left at a left place, right at a right place, and centred elsewhere. A text that builds nothing, such as an empty summary, takes no room.

A size written up to is fitted in the middle row: the texts there share the largest size, down to 45, at which the row fits. At the top or the bottom nothing is fitted, and up to is drawn at the size given.

Fonts

The fonts in font are tried in the order written, character by character, so a second font fills in what the first lacks, such as another script.

statac new --cards names Noto Sans and then Noto Emoji, so an emoji in a title is drawn, in the text’s colour. Statac has no font of its own.

Other cards

templates/og.<name>.yaml sets out another card, called <name>, in the same way, naming its files in templates/og/: og.wide.yaml is the card called wide. In a page’s front matter:

card: wide

A folder hands a card to its pages with pages.card: wide in its index.md, as any field is handed down. A page naming no card has the site’s own, templates/og.yaml.

A picture of your own

In a page’s front matter:

og_image: cover.jpg

The page is shared with this picture in place of a card, even where it names a card. The picture is found as one in the writing is, and published exactly as it is.

page.card gives its address, its size where the file has one, and as alt the description in the file beside it, or else what the page is called.

What a card waits for

note  No site address: sharing cards are left out until the site has a `url`
  templates/og.yaml, line 1
   1 │ # The sharing card drawn for each page: see /sharing-cards/
     │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Add the site's address to `statac.yaml`, as `url: https://example.org/`.
  More: https://statac.dev/e/no-site-address/

With no url, nothing is drawn and page.card has no value on any page. A build with --url draws the cards for that address.

A card is drawn for a draft whenever it is built: in serve’s preview, and with statac build --drafts.

When a card isn’t drawn

Kept between builds

Drew 16 cards.

Statac keeps each card it draws in .statac/, and draws it again only when its words, its settings or its files change. build says how many it drew.

After a build that publishes the site, the cards no page is shared with any more are removed. A build with --url adds cards and removes none.

statac check draws nothing, but builds and places each card’s texts, which finds the problems above.

Where next?

• Front matter: og_title, og_image and card, beside every other field
• Pictures: where a picture is found, and its description
• Templates: what a layout can show, and what headline calls a page
• Starting a site: statac new --cards, and bringing the card’s files up to date