Screenshot Automation in Docusaurus: Getting Started

Docusaurus has dark mode built in. Your docs adapt. Your code blocks adapt. Your screenshots? They just sit there, glaring white on a dark page.

You could maintain two versions of every image and write a custom component to swap them. Or you could automate it.

Heroshot is a CLI that captures screenshots and handles light/dark variants automatically. Here's how to set it up with Docusaurus.

Install

npm install heroshot

Add the plugin

// docusaurus.config.js
const { heroshot } = require('heroshot/plugins/docusaurus');

module.exports = {
  plugins: [heroshot()],
  // ... rest of your config
};

The plugin registers the manifest and sets up the output directory (static/heroshots/ by default).

Capture your first screenshot

Run heroshot:

npx heroshot

A browser opens with a visual picker. Start your Docusaurus dev server in another terminal, navigate to it, and click on the element you want to capture. Name it, close the browser.

You'll get two files:

• dashboard-light.png
• dashboard-dark.png

Use it in MDX

import { Heroshot } from 'heroshot/docusaurus';

<Heroshot name="dashboard" alt="Dashboard overview" />

The component renders a <picture> element that swaps between light and dark variants based on the user's theme. No flash, no reload.

Update screenshots

When your UI changes, just run npx heroshot again. All configured screenshots regenerate.

That's the basic setup. Once you're running, check out the features article for viewports, retina support, and CI/CD automation.

Docs: heroshot.sh/docs/integrations/docusaurus