How to Set Social Preview Images for a Documentation Website

To set a social preview image for a documentation page, make the generated HTML include an Open Graph og:image tag in its <head>, pointing to an image that the sharing service can fetch publicly. Use your documentation generator’s supported front matter, site configuration, page-head component, or social-card plugin. A Markdown image embedded in the page body does not configure its share preview.

What controls the preview

The sharing crawler reads metadata from the rendered page. At minimum, set og:image; for a more complete website share preview, LinkedIn’s guidance calls for og:title, og:image, og:description, and og:url. These tags belong in the HTML head, not just the Markdown content.

<meta property="og:title" content="API guide">
<meta property="og:description" content="Reference for the public API">
<meta property="og:url" content="https://docs.example.com/api/">
<meta property="og:image" content="https://docs.example.com/img/api-guide-social.png">

The image URL should be absolute when the target service requires it, publicly reachable without login, and return the intended image. The framework-specific examples below show where to configure the metadata; always inspect the deployed HTML to confirm the final URL and tags.

Choose the right implementation

Approach	Best for	What to verify
Per-page metadata	Pages that need distinct preview artwork	Each rendered page emits its own image URL
Global metadata	A consistent default image across the documentation site	Page-level values override or coexist as intended
Generated social cards	A distinct automatically created card for each page	Plugin version, site URL, generated assets, and final head tags
Repository social preview	A GitHub repository link	This is a repository setting, separate from documentation-page metadata

Pick a per-page image when the page topic should be recognizable in a feed. A global default is simpler to maintain, but readers may see the same image for every page. An automatic card plugin can reduce manual asset work, but adds generator and plugin configuration to maintain.

Docusaurus: set an image per Markdown page

Docusaurus supports an image front matter field for a thumbnail used in social media cards. Add it to the page’s front matter:

---
title: API guide
description: Reference for the public API
image: /img/api-guide-social.png
---

# API guide

Reference for the public API.

The path above is an example. Confirm how it resolves under your deployed site base URL, and inspect the generated page to ensure the emitted og:image is absolute and publicly fetchable if the target platform needs an absolute URL. Docusaurus also supports global metadata in site configuration. For React pages or custom page types, use the page head or Head component to provide the appropriate metadata.

Official guidance: Docusaurus SEO and metadata.

Material for MkDocs: generate social cards

Material for MkDocs provides a social plugin that can generate custom social preview cards for pages. Check the plugin documentation for the version installed in your project before copying configuration, since setup can depend on the current version. Configure site_url when required so the plugin can calculate absolute image URLs.

MkDocs copies image files and other non-Markdown assets into the generated site. That makes an image available as a site asset, but it does not by itself set the page’s preview metadata: the active theme or plugin still needs to emit the relevant tags and point them to the intended image.

Official guidance: Material for MkDocs social plugin and MkDocs site_url configuration.

GitHub repository previews are a separate setting

If you want to control the image shown when someone shares a GitHub repository, set the repository’s Social preview in repository Settings. That setting does not add og:image metadata to each page on your documentation website.

GitHub recommends repository preview images of at least 640 × 320 pixels and 1280 × 640 pixels for best display. It accepts PNG, JPG, or GIF under 1 MB for this repository feature. PNG transparency is supported, but the appearance can vary against dark and light backgrounds; use a solid background if you are unsure. These limits are GitHub repository-preview guidance, not universal requirements for documentation sites.

Source: GitHub social media previews.

Choose image dimensions and format for the target

There is no single size rule established here for every platform. LinkedIn’s website-sharing guidance gives a minimum image size of 1200 × 627 pixels. GitHub’s separate repository preview guidance differs. Check the current requirements for the service where readers will share your pages and choose an image that remains legible when cropped or scaled.

• Keep essential visual content away from the edges in case a preview is cropped.
• Ensure the image is publicly accessible and served as an image response.
• Prefer a solid background if transparency could look poor in light or dark contexts.
• Check the platform’s current accepted formats, dimensions, and file-size limits.

LinkedIn source: LinkedIn website sharing guidance.

Verify the deployed page

1. Build and deploy the documentation site so you can check the actual public output.
2. Open the page source or fetch the page HTML, then find og:image in the document head.
3. Confirm the metadata describes the intended page and the image URL is the intended one, absolute where required.
4. Open the image URL directly in a browser without being logged in. Confirm it returns the expected image.
5. Check the target platform’s image constraints and use its available preview mechanism if you need to inspect a share card.

For Docusaurus, inspect page-level front matter output; for Material for MkDocs, check the generated card and the metadata emitted by the plugin or theme. Validate the deployed page rather than assuming the source configuration produced the desired tags.

Or skip the browser setup

If you need an actual screenshot of the rendered documentation page as a social asset, ScreenshotNeo is a website screenshot API and MCP server. Here is the one-call API request; see the API documentation for options and response details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://docs.example.com/api/ -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://docs.example.com/api/"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://docs.example.com/api/' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. A screenshot is an image asset, while social preview metadata still needs to point to a publicly fetchable image URL.

Sign up for 1,000 free screenshots a month, with no card.

Troubleshooting

Symptom	Likely cause	Fix
The preview uses no image or an old image	The deployed head lacks the intended og:image, or the platform is showing cached preview data	Inspect the deployed HTML first. If it is correct, use the platform’s current refresh or preview tools where available; refresh behavior and timing vary.
The image URL works for you but not the crawler	The URL requires authentication, redirects unexpectedly, or is not publicly reachable	Test it in a logged-out browser and use a stable public URL.
The page has a body image but the card does not	A Markdown image was added without configuring head metadata	Set the generator’s supported social image metadata and inspect the rendered head.
A relative image path fails on deployment	The site base path or canonical host changes how the path resolves	Check the final generated tag and use a fully qualified URL if the target requires one.
Every page shows the same preview	Only global metadata is configured	Add per-page metadata or configure the generator’s social plugin for page-specific cards.
A plugin does not create absolute URLs	The site URL is missing or not configured as the plugin expects	Set the correct site_url, rebuild, and inspect the emitted image URL.
The image looks cropped or indistinct	Platform display dimensions or cropping differ from the source image	Check target-specific guidance and preview the composition at the likely rendered size.

Performance, reliability, and cost

Static metadata and pre-made image files add no browser rendering work for a share crawler beyond retrieving the page and image. Generated social cards can reduce manual per-page artwork, while introducing build-time plugin work and configuration that should be checked after upgrades. Keep image assets reasonably sized and hosted reliably so crawler fetches can complete.

Image creation and hosting costs depend on your workflow and infrastructure; the sources here do not establish universal costs or performance figures. A screenshot API can create a rendered-page image on demand, but it does not replace the metadata step: publish the resulting image at a fetchable URL and set that URL in the page head. ScreenshotNeo bills only clean shots; bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses report page verdict and billing headers.

FAQ

Will adding a Markdown image set the share preview?

No. Put the social image reference in metadata emitted into the HTML head.

Should every documentation page have its own image?

Only if page-specific previews are useful to your readers. A shared default is simpler to maintain; per-page metadata gives more relevant cards.

Can I use the GitHub repository image for my documentation pages?

The repository Social preview setting and website page metadata are separate. Configure the website’s head tags independently.

Will every platform show the same crop?

Do not assume so. Follow the target service’s current requirements and inspect its preview where possible.

Does a screenshot automatically become the social preview?

No. Host the screenshot at a public URL and set that URL as the page’s social image metadata.