Docusaurus Open Graph Tags: Add OG Meta to Your Docs Site

Docusaurus OG tag fundamentals

Docusaurus has built-in support for OG tags at both the site level (viadocusaurus.config.js) and per-page level (via frontmatter). For docs and blog posts, you control OG metadata through frontmatter fields. For the site-wide default, configure the metadata array in your config.

Site-wide OG defaults in docusaurus.config.js

// docusaurus.config.js
const config = {
  title: "My Docs",
  tagline: "Awesome documentation",
  url: "https://docs.example.com",
  
  themeConfig: {
    // Default OG image for all pages
    image: "img/og-default.png", // 1200×630, placed in static/img/
    
    metadata: [
      { name: "twitter:card", content: "summary_large_image" },
      { property: "og:type", content: "website" },
    ],
    
    navbar: { title: "My Docs", /* ... */ },
  },
};

module.exports = config;

Per-page OG tags via frontmatter

Override OG tags on individual docs pages or blog posts using frontmatter:

---
title: Getting Started
description: Learn how to install and configure the SDK in 5 minutes.
image: /img/docs/getting-started-og.png
keywords: [sdk, install, quickstart]
---

# Getting Started

...

Docusaurus automatically renders the description asog:description and meta:description. The image field sets og:image.

Per-page custom_edit_url and head metadata

For full control, use the head frontmatter key to inject arbitrary meta tags:

---
title: API Reference
description: Complete API reference documentation.
head:
  - tag: meta
    attributes:
      property: "og:image"
      content: "https://docs.example.com/img/api-reference-og.png"
  - tag: meta
    attributes:
      property: "og:image:width"
      content: "1200"
  - tag: meta
    attributes:
      property: "og:image:height"
      content: "630"
  - tag: meta
    attributes:
      name: "twitter:card"
      content: "summary_large_image"
---

Programmatic OG images with @docusaurus/plugin-ideal-image

For large docs sites, automate OG image generation at build time using a custom plugin:

// docusaurus.config.js — using a custom build-time OG generator
const config = {
  plugins: [
    [
      "./src/plugins/og-image-generator",
      {
        // Custom plugin that generates og:image for each page
        // using puppeteer or @vercel/og at build time
      },
    ],
  ],
};

// Or use the community plugin:
// npm install docusaurus-plugin-og-image

Docusaurus blog OG tags

Blog posts support the same frontmatter as docs pages, plus some extras:

---
title: "Introducing v2.0"
description: "A complete rewrite with improved performance and a new plugin API."
authors: [johndoe]
image: /img/blog/v2-release-og.png
tags: [release, announcement]
---

Docusaurus renders og:image, og:title, and og:description automatically from these fields. Theog:type is set to article for blog posts.

Common Docusaurus OG pitfalls

• Relative image paths: Always use absolute paths or ensure your url config is correct — Docusaurus prepends it to relative image paths
• Static asset location: Images in static/ are served from the root; reference them as /img/og.png (not img/og.png)
• SSR by default: Docusaurus uses SSG so OG tags are in the HTML — no extra configuration needed
• Versioned docs: Each versioned docs page should have its own OG image if possible, or fall back to the site default