Guide

Docusaurus Open Graph image

A Docusaurus site gets its share image from themeConfig.image in docusaurus.config.js. One doc or blog post can override it with image in its front matter. The classic theme turns that path into an absolute URL from your url and baseUrl, so a wrong url breaks every card on the site.

The site-wide image

The theme configuration reference calls this the meta image: a default image used for og:image and twitter:image. The value is a path relative to your site's static directory. It can also be an external URL. It cannot be an SVG.

// docusaurus.config.js
export default {
  url: 'https://docs.example.com',
  baseUrl: '/',
  themeConfig: {
    image: 'img/social-card.png',
  },
};

Put the file at static/img/social-card.png. A new site from the classic template already has img/docusaurus-social-card.jpg here. If you never replaced it, every page on your site shares the Docusaurus dinosaur card. Make the image 1200 × 630 pixels; Open Graph image size explains why.

One doc or blog post

The docs plugin and the blog plugin both accept image in front matter. Each reference describes it as the cover or thumbnail used as <meta property="og:image">.

---
title: Release 2.0
description: What changed in 2.0 and how to upgrade.
image: /img/release-2-card.png
---

That page now sends its own image. Pages without image keep the site-wide one. Set description in the same block, since Docusaurus uses it for og:description too. Open Graph title and description has the length limits.

A React page in src/pages has no front matter. Its SEO guide shows the <Head> component from @docusaurus/Head with an og:image meta tag inside. Use an absolute URL there, because <Head> prints what you give it.

Why url matters

In the theme source, the image goes through withBaseUrl(image, {absolute: true}) before it is written to og:image and twitter:image (metadataUtils.tsx). Absolute means it is prefixed with the url field from the site config, plus baseUrl.

So the card breaks when url is still https://your-docusaurus-site.example.com from the template, when it is a preview host, or when a GitHub Pages project site sets baseUrl wrong. The tag then points at a file that is not there, and apps show a title with no picture. Absolute og:image URL covers the general rule.

The tags a built page sends

The classic theme's SiteMetadata component writes og:url from the canonical URL and twitter:card as summary_large_image, then the default image. The docusaurus.io docs send this:

<meta name="twitter:card" content="summary_large_image" />
<meta property="og:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg" />
<meta name="twitter:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg" />

Docusaurus renders these into static HTML at build time, so link preview bots see them without running JavaScript. npm run start serves a dev build at localhost, which no app can fetch. Check the deployed URL, or run npm run build then npm run serve and read the HTML.

Extra tags with metadata

themeConfig.metadata takes a list of objects that become <meta> tags on every page. The SEO guide uses it for twitter:card. Do not add a second og:image there. Two image tags give each app a different choice, and the page-level front matter image stops being the one they pick.

Checklist

  1. url in docusaurus.config.js is the public origin, and baseUrl matches the deployed path.
  2. themeConfig.image points at a PNG or JPEG in static/, not the template card and not an SVG.
  3. Pages that are shared often set image and description in front matter.
  4. The built page has one og:image, and it opens in a browser.
  5. After a deploy, apps that cached the old card get a refresh: see Clear Open Graph cache.

The other static site generators are in Hugo, Eleventy, and Jekyll and GitHub Pages. Next.js and Astro are in OG tags by framework.

FAQ

Where does Docusaurus set og:image?

themeConfig.image in docusaurus.config.js, a path relative to static/. The classic theme writes it to og:image and twitter:image on every page. SVG is not accepted.

How do I give one page its own image?

Add image to that doc's or blog post's front matter. It replaces the site-wide image on that page only.

Why does og:image point at the wrong domain?

The absolute URL is built from url and baseUrl. Set url to the public origin, rebuild, and deploy.

What does a CardScope check cost?

A free check shows previews for X, LinkedIn, Slack, Discord, iMessage, Bluesky, Threads, Mastodon, WhatsApp, Telegram, and Microsoft Teams, plus the fix checklist. Pro is $19 once via Stripe Checkout, not a subscription: unlimited checks, a 50-page site audit with a CSV, share links, and PNG export. No account. A sample report shows a full result. A free audit checks the first 3 pages of a site and lists the rest. We parse HTML in memory and discard it — we do not store the page.