Astro Docs Without a Single Manual Screenshot

I set up an Astro docs site last week. Content collections, MDX pages, Starlight theme. Beautiful.

Then I needed screenshots. The dashboard page, the settings panel, the onboarding flow. Three screenshots, light and dark mode each, so six images total.

I spent an hour taking them by hand. Opened the app, resized the browser, captured, cropped, saved, repeated. Six times.

The next sprint, the onboarding flow changed. Screenshots were already stale.

Config-driven screenshots

Instead of capturing manually, define what you need:

{
  "outputDirectory": "src/assets/screenshots",
  "screenshots": [
    {
      "name": "dashboard",
      "url": "https://myapp.com/dashboard",
      "selector": ".dashboard-grid"
    },
    {
      "name": "settings",
      "url": "https://myapp.com/settings",
      "selector": ".settings-panel"
    },
    {
      "name": "onboarding",
      "url": "https://myapp.com/onboarding",
      "selector": ".onboarding-wizard"
    }
  ]
}

npx heroshot

Three config entries, six files. Light and dark variants are included automatically.

Using them in Astro

In your MDX file:

import { Image } from 'astro:assets';
import dashboard from '../../assets/screenshots/dashboard-light.png';

<Image src={dashboard} alt="Dashboard overview" />

Or if you want automatic dark mode switching, use a <picture> tag:

<picture>
  <source
    srcset="/screenshots/dashboard-dark.png"
    media="(prefers-color-scheme: dark)"
  />
  <img src="/screenshots/dashboard-light.png" alt="Dashboard" />
</picture>

Heroshot has a shortcut for this:

npx heroshot snippet

It generates the <picture> markup for every screenshot.

Astro + Starlight

If you're using Starlight (Astro's docs theme), screenshots go in src/assets/ so Astro optimizes them at build time. Set the output directory accordingly:

{
  "outputDirectory": "src/assets/screenshots"
}

Starlight handles responsive images, lazy loading, and format conversion automatically. You just provide the source PNGs.

Keeping them fresh

Add to your workflow:

# After every deploy
npx heroshot

# Check if anything changed
git diff --name-only src/assets/screenshots/

If screenshots changed, commit them. If nothing changed, move on.

Heroshot is open source and works with any static site generator. Astro, Next.js, VitePress, whatever. The config is framework-agnostic.