Home/Integrations/Docusaurus

DOCUSAURUS · DOCS THAT SHARE LIKE PRODUCTS

Give every guide and release note a recognizable card.

Turn Docusaurus document metadata into consistent social images during the build. Store the finished images in static/img/og, add an explicit frontmatter path, and keep rendering credentials out of the browser bundle.

Get 100 free rendersBrowse templates

Use the metadata Docusaurus already has

Documentation files normally include a title, description, sidebar label, and slug. Those are enough to generate a useful card. Add optional ogTemplate and ogAccent fields only when the page needs a different design.

--- title: Configure signed image URLs description: Embed public renders without exposing an API key. slug: /guides/signed-images image: /img/og/guides-signed-images.png ---

Render before the Docusaurus build

Use a Node script to scan Markdown and MDX frontmatter, render a card for entries whose tracked fields changed, and save the output under static/img/og. The image frontmatter value then points to a normal static asset copied into the deployment.

const query = new URLSearchParams({ title: doc.title, site: "docs.example.com", author: "Documentation", accent: doc.ogAccent || "#2563eb", }); const image = await fetch(`https://ogshot.dev/v1/template/article?${query}`, { headers: { "x-api-key": process.env.OGSHOT_API_KEY }, }); if (!image.ok) throw new Error(`OG render failed for ${doc.slug}`); await writeFile(`static/img/og/${safeSlug(doc.slug)}.png`, Buffer.from(await image.arrayBuffer()));

Add the script before docusaurus build in the package scripts. Keep the API key in the CI environment and out of customFields, which may be exposed to client-side code.

Set a global fallback, then override pages

Docusaurus supports a site-level social card through themeConfig.image. Use that for utility pages, while documentation and blog frontmatter supply the generated page-specific asset. This ensures every route has a usable fallback without making every low-value page consume a render.

// docusaurus.config.js export default { url: "https://docs.example.com", themeConfig: { image: "img/og/default.png", metadata: [{ name: "twitter:card", content: "summary_large_image" }], }, };

Use specialized cards for releases

The changelog and announce templates are better fits for version launches than a generic article card. Map release-note files to changelog, pass the version as a tag, and include the two or three changes a reader should recognize at a glance. Documentation guides can continue using the article template.

Animated templates can produce GIF, WebP, or MP4 output, but use motion deliberately. Discord and Slack can display animated unfurls; other platforms receive or cache still imagery differently. A settled PNG remains the safest general-purpose default for documentation.

Hash the title, description, template, accent, and design version. Documentation body edits that do not affect the card should not trigger a new render.

Inspect the production route

Theme customization and plugins can override metadata after the build. Check the deployed page with the OG image inspector rather than assuming the frontmatter won. Verify both a documentation page and a blog post, since Docusaurus processes them through different plugins.

Related guides: Next.js, Hugo, and Satori alternative.

DOCUSAURUS · SHIP THE DOCS CARD

Make the next guide recognizable in the feed.

Start with 100 free renders and unmetered cache hits.

Create an API keyInspect your docs