Reference

Every tag the social extension emits.

The complete social configuration: the resolution order for each tag, every option, and the overlap with Quarto’s own metadata.

Enabling the filter

filters:
  - social

Metadata resolution

Each tag is resolved from the first available standard source, then from the scoped fallback under extensions.social.

Where each tag’s value comes from.
Emitted tag Standard source Scoped fallback
og:title, twitter:title open-graph.title, twitter-card.title, title title
description, og:description, twitter:description open-graph.description, twitter-card.description, description description
og:image, twitter:image open-graph.image, twitter-card.image, image image
og:image:width, og:image:height open-graph.image-width, open-graph.image-height image-width, image-height
og:image:alt, twitter:image:alt open-graph.image-alt, image-alt image-alt
og:site_name open-graph.site-name site-name
og:locale open-graph.locale, lang locale
og:url site-url url, site-url
og:type none type
og:image:type none image-type
twitter:card twitter-card.card-style card-style
twitter:site, twitter:creator twitter-card.site, twitter-card.creator twitter-site, twitter-creator

og:url is the one exception to that order: extensions.social.url is read before the document’s site-url, not after it. og:type and og:image:type have no standard source at all and are read only from extensions.social.

The four properties Open Graph requires, og:title, og:type, og:image, and og:url, are written whenever a value is available. og:type falls back to website, og:image:type to the media type inferred from the file extension, and og:image:secure_url is added when the image URL is HTTPS.

The alternative text is read from open-graph.image-alt, then from a top-level image-alt, then from extensions.social.image-alt. Quarto reads the top-level key as well, so a deck that sets only that gets og:image:alt from both sources. A site-level open-graph.image-alt overrides the deck key for Quarto’s copy alone, which is why the two copies on this site carry different text.

Options

extensions:
  social:
    site-url: "https://example.com/my-talk/"
    image: "assets/social-card.png"
    image-width: "1200"
    image-height: "630"
    image-alt: "Title slide of the talk."
    site-name: "My Talks"
    twitter-creator: "@myhandle"
Options under extensions.social.
Option Type Default Description
enabled boolean true Set to false to stop the filter emitting anything.
title string document title Card title.
description string document description Card description.
image string document image Card image, as a path or a URL.
image-width, image-height string Image dimensions in pixels.
image-alt string Alternative text for the image.
image-type string inferred Media type, such as image/png.
locale string document lang Locale for og:locale, such as en_GB.
site-name string Value for og:site_name.
site-url string Base URL, used to make relative image paths absolute.
url string site-url Canonical page URL for og:url.
type string website Value for og:type.
card-style string summary_large_image when an image is set Value for twitter:card.
twitter-site, twitter-creator string The @username of the site and of the creator.
Warningenabled takes a boolean alone

The filter reads enabled through the extension schema, which accepts true and false alone, quoted or not. Any other value, yes and no included, is reported and leaves the filter running. The Switching off example shows what each spelling does.

extensions:
  social:
    enabled: false

Overlap with Quarto

Important

Quarto emits social tags for RevealJS by itself on current versions, which it did not when this extension was written.

The deck this site renders receives sixteen tags with no filter. The filter writes nineteen: five the deck did not have, and fourteen it already had, which then appear in the head twice.

What each source contributes.
Tags
Written by Quarto only twitter:image-width, twitter:image-height
Written by the filter only description, og:type, og:url, og:image:type, og:image:secure_url
Written by both og:title, og:description, og:image, og:image:alt, og:image:width, og:image:height, og:locale, og:site_name, twitter:card, twitter:title, twitter:description, twitter:image, twitter:image:alt, twitter:creator

These counts are for a deck that gives open-graph.image-width and open-graph.image-height itself, and whose image exists. Quarto derives both values from the image file whatever the deck says, and the filter writes the two tags only when the deck gives them. Leave them out and the two tags move to the Quarto row. Give them and point the deck at a missing image, and they move to the filter row.

Eleven of the fourteen duplicated tags carry the same value twice. Three do not:

  • og:site_name. The two sources swap inside a website. The filter’s copy carries the site title, and Quarto’s carries the value given under open-graph.site-name. Render the same deck without the filter and Quarto’s copy carries the site title instead. The filter does not change what Quarto writes. Quarto puts open-graph.site-name in its own tag, then overwrites the first og:site_name tag in the head with the site title. With the filter present that first tag is the filter’s, so the two look as though they have traded values. This is a bug in Quarto, reported as quarto-dev/quarto-cli#14917. Outside a website the filter’s copy carries open-graph.site-name.
  • og:image:alt and twitter:image:alt. Quarto describes the site’s own social card, and the filter describes the image the deck set.

The filter writes its tags as one block, and Quarto writes its own block after it. A scraper reads the first copy it meets, which is the filter’s. The Examples page compares the two decks directly.

Quarto reaches into the filter’s block for four more tags. It picks og:title, twitter:title, og:description and twitter:description by position as well, rather than by who wrote them. The values usually match what the filter wrote, so nothing looks out of place. When they differ, Quarto wins. The filter writes the deck title on its own, and both copies come back with the site title appended.

Limitations

Warning

Social scrapers need an absolute og:image URL. Set site-url so a relative path resolves against it, or give an absolute URL. The filter warns when a relative path is used without one.

  • RevealJS only.
  • The tags Quarto now writes itself are written again, as above.
Back to top