DEV Community

Ondrej Machala
Ondrej Machala

Posted on

Astro Docs Without a Single Manual Screenshot

#astro #documentation #webdev #automation

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. Six screenshots, light and dark mode each, so twelve images total.

I spent an hour taking them by hand. Opened the app, resized the browser, captured, cropped, saved, repeated. Twelve 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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode 
npx heroshot
Enter fullscreen mode Exit fullscreen mode

Six screenshots captured. Light and dark variants included automatically. That's twelve files from three config entries.

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" />
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Heroshot has a shortcut for this:

npx heroshot snippet
Enter fullscreen mode Exit fullscreen mode

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 accordinly:

{
  "outputDirectory": "src/assets/screenshots"
}
Enter fullscreen mode Exit fullscreen mode

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 heroshots/
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)