OG Images for Documentation Sites: Make Docs Links Look Great When Shared

Why docs OG images matter

Documentation links get shared constantly — in Slack, Discord, GitHub issues, Twitter threads, and LinkedIn posts. When your docs link shows a blank card or just a favicon, developers skip it. When it shows a clean, readable preview with the page title and section, developers click it.

The goal for docs OG images is different from marketing pages: you want clarity and immediate context ("this is the page about X in Y docs"), not marketing appeal.

The three docs OG strategies

1. Static default OG image

The simplest approach: one branded OG image for the entire docs site. Low effort, but every shared link looks identical regardless of which page is shared.

<!-- Minimum viable docs OG setup -->
<meta property="og:image" content="https://docs.example.com/og-default.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

2. Per-page frontmatter OG

Each page specifies its own OG image in frontmatter. High relevance, high manual effort. Best for high-traffic landing pages in your docs.

3. Dynamic OG images (recommended)

Auto-generate OG images at request time using the page title, section, and brand. Zero manual effort per page, consistent branding, and every page gets a unique card.

Dynamic OG image template for docs

A good docs OG image shows: the product name, the page/section title, and ideally the section hierarchy (e.g., "API Reference → Authentication"). Here's a Next.js example:

// app/api/og/route.tsx
import { ImageResponse } from "next/og";

export const runtime = "edge";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get("title") || "Documentation";
  const section = searchParams.get("section") || "";

  return new ImageResponse(
    (
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          background: "#111827",
          width: "100%",
          height: "100%",
          padding: "60px 80px",
          justifyContent: "space-between",
        }}
      >
        {/* Product logo / name */}
        <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
          <div
            style={{
              width: 48,
              height: 48,
              borderRadius: 12,
              background: "#6366f1",
              display: "flex",
              alignItems: "center",
              justifyContent: "center",
              fontSize: 28,
              color: "#fff",
            }}
          >
            📘
          </div>
          <span style={{ fontSize: 28, fontWeight: 700, color: "#e2e8f0" }}>
            Your Product Docs
          </span>
        </div>

        {/* Page title and section */}
        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
          {section && (
            <div style={{ fontSize: 22, color: "#6366f1", fontWeight: 600 }}>
              {section}
            </div>
          )}
          <div
            style={{
              fontSize: 52,
              fontWeight: 900,
              color: "#f8fafc",
              lineHeight: 1.2,
            }}
          >
            {title}
          </div>
        </div>

        {/* Footer */}
        <div style={{ fontSize: 22, color: "#64748b" }}>docs.example.com</div>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

Wiring OG into your docs framework

Depends on your docs platform:

• Docusaurus: Use image frontmatter or themeConfig.image for defaults. Point to your dynamic route.
• Nextra: Add og:image via the head block in _meta.json or theme config.
• VitePress: Use head in frontmatter or themeConfig.socialLinks image.
• GitBook: Configure OG in Space settings → SEO section.
• Mintlify: Set openGraph in mint.json, or use frontmatter on individual pages.
• ReadTheDocs: Override HTML templates to inject OG tags.

What makes a good docs OG image

• Product name visible: Developers need to know which product's docs they're looking at instantly
• Page title legible: Large font (48px+), high contrast — it's read on mobile previews
• Section breadcrumb: "API Reference → Authentication" tells users exactly where they'll land
• Dark background: Most developer communities (Discord, GitHub) are dark-mode — dark OGs look native
• No marketing copy: Docs audiences are already users; they don't need to be sold. Context > conversion.