DEV Community

Ondrej Machala
Ondrej Machala

Posted on • Edited on

Your Docusaurus Screenshots Break on Mobile and Retina Displays

#react #documentation #docusaurus #webdev

You took screenshots of your Docusaurus docs. They look fine on your monitor.

On a phone? The layout breaks. On a retina display? Blurry. In dark mode? White background glaring against a dark page.

You captured one screenshot per page. You actually needed four: desktop and mobile × light and dark.

Here's how to automate all of it with heroshot.

Responsive screenshots

Add viewports to your config:

{
  "name": "dashboard",
  "url": "http://localhost:3000/dashboard",
  "selector": ".main-content",
  "viewports": ["desktop", "mobile"]
}
Enter fullscreen mode Exit fullscreen mode

One config entry. Four screenshots: desktop-light, desktop-dark, mobile-light, mobile-dark.

The <Heroshot> component handles srcset automatically:

<Heroshot name="dashboard" alt="Dashboard" />
Enter fullscreen mode Exit fullscreen mode

Readers get the right size for their device. No JavaScript. No manual switching.

Retina support

Add one line to any screenshot config:

{
  "name": "dashboard",
  "deviceScaleFactor": 2
}
Enter fullscreen mode Exit fullscreen mode

Captures at 2x resolution. Docs look sharp on every display.

CI/CD

Regenerate on every deploy:

- name: Update screenshots
  run: npx heroshot --headless

- name: Commit if changed
  run: |
    git diff --quiet static/heroshots/ || \
    (git add static/heroshots/ && git commit -m "Update screenshots")
Enter fullscreen mode Exit fullscreen mode

Or on a schedule — weekly, nightly, whatever fits your release cadence:

on:
  schedule:
    - cron: '0 0 * * 0'
Enter fullscreen mode Exit fullscreen mode

Theme detection

The component watches <html data-theme="dark"> for changes. When users toggle Docusaurus's theme, screenshots swap instantly. No page reload, no flash.

Under the hood it's a <picture> element:

<picture>
  <source srcset="dashboard-dark.png" media="(prefers-color-scheme: dark)" />
  <source srcset="dashboard-dark.png" media="[data-theme=dark]" />
  <img src="dashboard-light.png" alt="Dashboard" />
</picture>
Enter fullscreen mode Exit fullscreen mode

One-offs

Need a quick capture without touching config?

npx heroshot https://your-app.com --dark --light --mobile
Enter fullscreen mode Exit fullscreen mode

Three flags, up to six files.

New to heroshot? Start with the Docusaurus integration guide.

heroshot.sh — free, open source.

Top comments (0)