Documentation Hero Image Fallbacks (Docusaurus, VitePress)
Prevent broken hero images in Docusaurus and VitePress documentation sites with docusaurus og image fallbacks and URL-based placeholder patterns for docs sites.
Documentation sites built with Docusaurus or VitePress often have hero images on the homepage, OG images for individual doc pages, and illustrative screenshots inside guides. These images are frequently missing for new doc pages, outdated after UI changes, or broken when the docs site moves hosts. Setting up documentation hero image fallbacks prevents these gaps from surfacing as broken icons or missing OG cards.
The fallback.pics API generates page-specific OG images and in-page placeholder images from URL parameters. For documentation sites, this means every page can have a descriptive OG image and every hero slot can have a brand-consistent fallback—automatically, from the page title.
Docs site image failures
Where documentation site images break most often
The most common failure is the OG image. Docusaurus and VitePress support a custom_edit_url and a custom image field in the frontmatter, but they do not auto-generate OG images for pages that lack a custom image. Those pages use whatever fallback OG image the site has configured globally—or no image at all if none is configured.
Screenshot images inside guides are the second failure point. Docs screenshots are captured from a specific UI version and go stale with every redesign. A screenshot referenced by a hardcoded path may return a 404 after a docs reorganization or a static asset migration.
Hero images on landing pages and homepage hero sections are the third: often referenced from the same CDN as the application, which creates the same infrastructure dependency problem that affects status pages.
OG image per page
Generate per-page OG images in Docusaurus with the thumbnail route
In Docusaurus, you can add custom OG image generation to the page configuration or use a Docusaurus plugin. The simplest approach without a plugin is to add a @theme/DocItem/Layout swizzle that injects a computed og:image meta tag based on the page title.
The thumbnail route accepts the page title as the text parameter and produces a 1200x630 image branded with your doc site color. No external plugin or build-time image generation required—the URL is computed at render time.
// Docusaurus swizzle: src/theme/DocItem/Layout/index.js
import React from 'react';
import Layout from '@theme-original/DocItem/Layout';
import Head from '@docusaurus/Head';
import { useDoc } from '@docusaurus/theme-common/internal';
export default function DocItemLayout(props) {
const { frontMatter, metadata } = useDoc();
const ogImage =
frontMatter.image ??
`https://fallback.pics/api/v1/thumbnail/1200x630?text=${encodeURIComponent(metadata.title.slice(0, 40))}&style=soft&theme=purple&label=Docs`;
return (
<>
<Head>
<meta property="og:image" content={ogImage} />
<meta name="twitter:image" content={ogImage} />
</Head>
<Layout {...props} />
</>
);
}VitePress
VitePress per-page OG images with the transformPageData hook
VitePress provides a transformPageData hook in the config that runs for every page during the build. Use it to inject a computed og:image into the page head when the frontmatter does not include a custom image.
This approach generates all OG image URLs at build time, which means they appear in the pre-rendered HTML and are available for social crawlers that do not execute JavaScript.
// .vitepress/config.mts
export default defineConfig({
transformPageData(pageData) {
const image =
pageData.frontmatter.image ??
`https://fallback.pics/api/v1/thumbnail/1200x630?text=${encodeURIComponent(pageData.title.slice(0, 40))}&style=soft&theme=purple&label=Docs`;
pageData.frontmatter.head ??= [];
pageData.frontmatter.head.push(
['meta', { property: 'og:image', content: image }],
['meta', { name: 'twitter:image', content: image }],
);
},
});Hero images
Homepage hero and docs landing page image fallbacks
Documentation site homepage heroes are typically wide-format images (1440x600 or 1200x500) that showcase the product or technology the docs describe. These images are maintained by whoever owns the docs site and can go stale or break during site migrations.
Add an onerror fallback to the hero img element that generates a branded placeholder at the same dimensions. For a docs site, a purple-on-white or dark-on-brand-color placeholder with the product name communicates the brand without requiring a custom illustration.
<!-- Docusaurus homepage hero with fallback -->
<img
src="/img/hero.png"
width="1200"
height="500"
alt="Product hero image"
onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/1200x500/7C3AED/FFFFFF?text=Your+Product'"
/>Screenshot guides
Handle stale screenshots in written guides
Screenshots inside documentation guides break silently. The image was valid when the page was written, but a UI redesign or a docs reorganization can break the path. Browser DevTools will show 404 errors in the console, but neither the author nor the reader is alerted.
Add a global onerror handler that catches all broken images in your docs site and replaces them with a 'Screenshot outdated' placeholder. This surfaces the problem visually to readers who can then file an issue, instead of silently serving a broken page.
// docusaurus.config.js: inject global onerror via scripts
module.exports = {
scripts: [
{
src: '/js/image-fallback.js',
async: true,
},
],
};
// static/js/image-fallback.js
document.addEventListener('DOMContentLoaded', function () {
document.querySelectorAll('article img').forEach(function (img) {
img.addEventListener('error', function () {
if (img.src.startsWith('https://fallback.pics')) return;
img.onerror = null;
img.src =
'https://fallback.pics/api/v1/800x400/F4F4F5/9CA3AF?text=Screenshot+Outdated';
});
});
});Nextra / Mintlify
Other docs frameworks: apply the same per-page OG pattern
Nextra (Next.js-based) and Mintlify both support custom head injection per page. In Nextra, use the _document.tsx or _app.tsx to inject the computed og:image. In Mintlify, the og:image can be set in the page frontmatter or in the global config.
For any docs framework that does not support auto-generated OG images, the thumbnail URL approach produces a consistent, page-specific image from the title with zero build-time processing.
// Nextra: per-page OG image in MDX frontmatter
---
title: Getting Started
image: https://fallback.pics/api/v1/thumbnail/1200x630?text=Getting+Started&style=soft&theme=purple&label=Docs
---Key takeaways
What to standardize before shipping
- Docusaurus and VitePress do not auto-generate per-page OG images; inject a thumbnail URL computed from the page title with a swizzle or transformPageData hook.
- VitePress transformPageData runs at build time so OG meta tags appear in pre-rendered HTML, available to social crawlers before JavaScript executes.
- Add a global article img onerror handler in Docusaurus to replace stale screenshots with a visible 'Screenshot Outdated' placeholder.
- For homepage heroes, use an onerror fallback at the same dimensions to handle CDN failures during site migrations.
- The thumbnail URL is deterministic—compute it from the page title in any docs framework that supports custom head injection.
Production fallback layer
Use fallback.pics anywhere an image URL is accepted.
Start with one deterministic URL and standardize fallback behavior across your design system.
Continue reading
Related articles
Changelog and Release Note Header Images from Text
Generate changelog header images automatically from release version text using fallback.pics thumbnail URLs—no design work required for every release.
OG Image Placeholders for Blogs, Docs, and Social Sharing
Use generated OG image placeholders for blog posts, documentation pages, changelogs, and social previews while final artwork is unavailable.
Generate Blog Thumbnails from Text When Featured Images Are Missing
Use fallback.pics thumbnail URLs to generate blog featured images from post titles, category labels, themes, and safe-zone background styles.