Open Graph Tags for Documentation Sites: A Complete Setup Guide

Add OG meta tags to your docs site — covers Docusaurus, GitBook, Mintlify, ReadTheDocs, Nextra, and Starlight with copy-paste examples.

Why documentation sites need good OG tags

Documentation pages are shared constantly — in Slack, Discord, GitHub issues, Twitter, and team wikis. When someone pastes a docs URL and the preview shows a blank image or generic site name, it creates friction. Good OG tags on docs pages:

  • Increase clicks from shared links in chat and social media.
  • Make your docs look professional when shared in GitHub issues or PRs.
  • Help users identify the right page before clicking (especially for deep links).

Each documentation platform handles OG tags differently. Here's how to set them up in the most popular ones.

Docusaurus

Docusaurus v3 generates OG tags automatically from page metadata. Customize the site-wide defaults in docusaurus.config.js and per-page overrides in front matter:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    image: "img/social-card.png",   // Default og:image for all pages
    metadata: [
      { name: "twitter:card", content: "summary_large_image" },
      { name: "twitter:site", content: "@yourhandle" },
    ],
  },
};

// Per-page front matter (docs/getting-started.md)
---
title: Getting Started
description: Install and configure MyLib in under 5 minutes.
image: /img/og/getting-started.png   # Overrides site default
---

Docusaurus automatically sets og:title, og:description, and og:url from the page title, description, and URL. You only need to provide the image.

Nextra (Next.js docs)

Nextra is built on Next.js. Use the _meta.json or front matter in MDX files, and add OG tags via the Next.js Metadata API in a layout:

// pages/_app.tsx or app/layout.tsx (App Router)
import type { Metadata } from "next";

export const metadata: Metadata = {
  openGraph: {
    siteName: "My Docs",
    images: [{ url: "https://yourdomain.com/og/default.png" }],
  },
  twitter: { card: "summary_large_image" },
};

// Per-page: pages/docs/getting-started.mdx
---
title: Getting Started
description: Install and configure MyLib quickly.
---

import { useConfig } from "nextra-theme-docs";
// Or set in nextra theme config:

// theme.config.tsx
const config = {
  useNextSeoProps() {
    return {
      openGraph: {
        images: [{ url: "https://yourdomain.com/og/default.png" }],
      },
    };
  },
};

Starlight (Astro)

Astro Starlight auto-generates basic OG tags. Set a site-wide social image in astro.config.mjs:

// astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My Docs",
      social: { github: "https://github.com/yourorg/repo" },
      // Default OG image for all pages:
      head: [
        {
          tag: "meta",
          attrs: { property: "og:image", content: "https://yourdomain.com/og/default.png" },
        },
        {
          tag: "meta",
          attrs: { name: "twitter:card", content: "summary_large_image" },
        },
      ],
    }),
  ],
});

// Per-page: src/content/docs/getting-started.mdx
---
title: Getting Started
description: Install and configure MyLib quickly.
head:
  - tag: meta
    attrs:
      property: og:image
      content: https://yourdomain.com/og/getting-started.png
---

GitBook, Mintlify, and ReadTheDocs

GitBook

GitBook auto-generates OG tags from page titles and your space description. Upload a custom social image in Space Settings → Social Preview. There is no per-page OG image override in GitBook's standard plan — all pages share the site image.

Mintlify

Mintlify reads og:image from your mint.json configuration file:

// mint.json
{
  "name": "My Docs",
  "openapi": "/api.json",
  "favicon": "/favicon.svg",
  "metadata": {
    "og:image": "https://yourdomain.com/og/default.png",
    "twitter:card": "summary_large_image",
    "twitter:site": "@yourhandle"
  }
}

ReadTheDocs

ReadTheDocs uses Sphinx or MkDocs themes. For MkDocs with the Material theme, add OG tags via the extra config or a custom HTML override in overrides/main.html:

{# overrides/main.html — MkDocs Material theme #}
{% extends "base.html" %}
{% block extrahead %}
  <meta property="og:title"       content="{{ page.title }} | {{ config.site_name }}" />
  <meta property="og:description" content="{{ page.meta.description | default(config.site_description) }}" />
  <meta property="og:image"       content="{{ config.site_url }}assets/social.png" />
  <meta property="og:url"         content="{{ page.canonical_url }}" />
  <meta name="twitter:card"       content="summary_large_image" />
{% endblock %}

Test your docs OG tags free

Paste any documentation page URL into OGFixer to see previews on Twitter, LinkedIn, Discord, and Slack.

Related guides