Social Cards

When someone shares a link to your documentation on LinkedIn, Discord, Slack, Bluesky, Mastodon, X (Twitter), or other platforms, social card meta tags control the preview that appears. Great Docs automatically generates Open Graph and Twitter Card meta tags for every page so your links look polished rather than bare URLs.

What’s Generated

For every page in your site, Great Docs adds two sets of <meta> tags to <head>:

Open Graph (used by LinkedIn, Discord, Slack, Bluesky, Mastodon, Facebook, and most other platforms):

<meta property="og:type" content="website">
<meta property="og:title" content="Configuration | My Package">
<meta property="og:description" content="How to configure My Package...">
<meta property="og:url" content="https://user.github.io/pkg/user-guide/config.html">
<meta property="og:site_name" content="My Package">
<meta property="og:image" content="https://user.github.io/pkg/social-card.png">

Twitter/X Card (used by X for its own preview cards):

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Configuration | My Package">
<meta name="twitter:description" content="How to configure My Package...">
<meta name="twitter:image" content="https://user.github.io/pkg/social-card.png">
<meta name="twitter:site" content="@myhandle">

These tags are generated per-page with the correct title, description, and URL for each page.

Zero-Config Defaults

Social card tags are enabled by default. With no configuration at all, Great Docs will:

  • use the page <title> for og:title and twitter:title
  • use the page’s meta description for og:description and twitter:description
  • fall back to the package description from pyproject.toml when no page-level description is available
  • build the og:url from your canonical base URL (auto-detected from GitHub Pages)
  • set twitter:card to "summary" (no image) or "summary_large_image" (when the card has an image)

No changes to great-docs.yml are needed for basic social card previews.

Adding a Social Card Image

An image makes a dramatic difference in how your links appear. Without one, most platforms show a plain text card. With a well-designed image, your link gets a large visual preview that stands out in feeds and chat messages.

Configuring the Default Image

Place your image in the project’s assets/ directory. This is the same directory Great Docs already copies into the build for logos, favicons, and other static files:

my-package/
├── assets/
│   ├── social-card.png   ← your social card image
│   ├── logo.svg
│   └── favicon.svg
├── my_package/
├── great-docs.yml
└── pyproject.toml

Then reference it in great-docs.yml:

docs/great-docs.yml
social_cards:
  image: assets/social-card.png

This single image is used as the default og:image and twitter:image for every page on your site. It’s copied to the site root during build and referenced with an absolute URL.

Page Images

When no site image is configured, Quarto chooses a card image from the page. It looks first for an image with the preview-image class, then for an image with a preview file name, and finally for the first local image in the page content:

user_guide/04-plotting.qmd
![A finished plot](images/plot.png){.preview-image}

Set image in a page’s front matter to override both the configured site image and images chosen from the page:

user_guide/04-plotting.qmd
---
title: "Plotting"
image: images/plot.png
---

Keep that image in a folder of assets beside the page, such as images/, or also use it in the page’s content. An image that only the front matter mentions is not otherwise copied into the site.

Cards with an image use the "summary_large_image" Twitter/X format unless you set twitter_card.

What to Put in the Image

A good social card image typically includes:

  • your package logo or wordmark
  • the package name in large, readable text
  • a short tagline or description
  • a subtle background color or pattern that matches your brand

Avoid putting page-specific information in the image since it’s shared across all pages. Focus on making the package itself recognizable.

Design Tips

  • High contrast text: white or light text on a dark background (or vice versa) ensures readability at small sizes
  • Large text: the image is often shown at 300-400 pixels wide in feeds; small text becomes unreadable
  • Simple composition: one logo, one title, one line of description is enough
  • Test at small sizes: preview your image at 300 × 157 pixels to see how it looks in a typical feed

Configuration Reference

The full social_cards configuration with all options:

docs/great-docs.yml
social_cards:
  enabled: true                          # Master switch (default: true)
  image: assets/social-card.png          # Default og:image path or URL
  twitter_site: "@myhandle"              # Twitter/X site @handle
  twitter_card: summary_large_image      # Card type override

Options

You can enable or disable social card meta tag generation. The default is true.

docs/great-docs.yml
# Disable social cards entirely
social_cards:
  enabled: false

You can also use the shorthand form:

docs/great-docs.yml
social_cards: false

The image key needs a path to a default image file (relative to the configuration directory) or an absolute URL. This image is used as og:image and twitter:image for all pages.

docs/great-docs.yml
# Local file (copied to site root during build)
social_cards:
  image: assets/social-card.png

# External URL (used as-is)
social_cards:
  image: https://cdn.example.com/my-package-card.png

When a card has an image, the twitter:card type automatically switches from "summary" to "summary_large_image" for a bigger preview on X.

The twitter_site key refers to the Twitter/X @handle for the site or organization. This appears in the card footer on X.

docs/great-docs.yml
social_cards:
  twitter_site: "@posaboron"

The @ prefix is optional (Great Docs will add it if missing).

Regarding twitter_card, this overrides the Twitter card type. By default, Great Docs chooses automatically:

  • "summary" when the card has no image
  • "summary_large_image" when the card has an image

Set this to force a specific type regardless of image presence:

docs/great-docs.yml
social_cards:
  image: assets/social-card.png
  twitter_card: summary  # Use small card even though an image exists

Card Descriptions

Cards use the page’s meta description. Great Docs chooses it in this order:

  1. Use description or description-meta from the page’s front matter, or the docstring summary for an API reference page.
  2. Use the <meta name="description"> in the site’s header includes, if there is one.
  3. Use the page’s opening paragraph if it has at least 30 characters of text.
  4. Use seo.default_description from great-docs.yml, falling back to the package description in pyproject.toml.

For the best previews, add a description to important pages’ frontmatter:

user_guide/03-configuration.qmd
---
title: "Configuration"
description: "Complete guide to configuring Great Docs, including theming, navbar styles, and SEO settings."
---

Page Overrides

Set open-graph or twitter-card in a page’s front matter to customise its card:

user_guide/03-configuration.qmd
---
title: "Configuration"
open-graph:
  title: "Configure My Package"
  description: "Every option in one place."
twitter-card:
  title: "Configure My Package"
---

When a page sets either key, Great Docs leaves both card titles and descriptions to Quarto. A mapping, as above, retains the configured site image and Twitter/X handle.

To supply your own social card tags across the site, add og: tags to the site’s header includes. Great Docs then stops generating social card tags for pages rendered by Quarto. A page whose own include-in-header or header-includes declares og: tags likewise gets none of the generated ones. Quarto still replaces the content of the first og:title on every page with the page title.

Testing Your Social Cards

After building your site, you can verify the meta tags are present by inspecting any HTML file:

Terminal
grep -E 'og:|twitter:' docs/_site/index.html

To see how your links will actually appear on each platform, use these free preview tools:

These tools fetch your live URL, so you’ll need to deploy your site first (or use a tunnel for local testing).

Relationship to SEO

Social cards work alongside the SEO features but serve a different purpose:

  • SEO optimizes how your pages appear in search engine results (Google, Bing)
  • Social cards control how your links appear when shared on social platforms

Both features can be enabled independently. Social cards use some of the same underlying data (canonical URLs, meta descriptions) but generate separate meta tags (og:* and twitter:*).

Disabling Social Cards

To turn off social card meta tags entirely you can use:

docs/great-docs.yml
social_cards: false

Or equivalently:

docs/great-docs.yml
social_cards:
  enabled: false

With either of these settings, the Open Graph and Twitter Card meta tags will not be injected into any pages.

Next Steps

Social cards control how your documentation looks when shared on Twitter, Slack, Discord, and other platforms. Great Docs generates the right meta tags automatically from your page titles and descriptions.

  • SEO Optimization covers search engine visibility, sitemaps, and canonical URLs
  • Configuration covers all great-docs.yml options including social card settings
  • Deployment explains publishing to GitHub Pages where social cards take effect