Keep Your MkDocs Screenshots Up to Date (Material Theme)

You've got MkDocs with Material theme. Dark mode works. Code blocks adapt. But your screenshots? Still stuck in light mode.

Here's how to fix that with Heroshot - a CLI that captures screenshots and handles light/dark variants automatically.

Step 1: Install the CLI

Pick your preferred method:

curl (standalone binary):

curl -fsSL https://heroshot.sh/install.sh | sh

Homebrew:

brew install omachala/heroshot/heroshot

npm:

npm install -g heroshot

Docker:

docker pull heroshot/heroshot

Step 2: Install the Python package

The CLI captures screenshots. The Python package provides the MkDocs macro:

pip install heroshot

Step 3: Configure output directory

MkDocs serves from docs/. Create .heroshot/config.json:

{

  "outputDirectory": "docs/heroshots"

}

Your structure:

my-project/

├── docs/

│   ├── index.md

│   └── heroshots/    # screenshots go here

├── mkdocs.yml

└── .heroshot/

    └── config.json

Step 4: Capture screenshots

Start your MkDocs dev server:

mkdocs serve

In another terminal, run heroshot:

heroshot

(Or npx heroshot / docker run --rm -v $(pwd):/work heroshot/heroshot depending on install method)

A browser opens with a visual picker. Navigate to localhost:8000, click on elements you want to capture, name them. Close when done.

You'll get two files per screenshot:

• dashboard-light.png


• dashboard-dark.png

Step 5: Add the macro

Update your mkdocs.yml:

plugins:

  - macros:

      modules: [heroshot]

Use it in your markdown:

{{ heroshot("dashboard", "Dashboard overview") }}

The macro expands to Material's #only-light / #only-dark syntax. When readers toggle the theme, screenshots swap automatically.

Step 6: Keep them fresh

When your UI changes:

heroshot

All configured screenshots regenerate. No manual cropping, no file hunting.

Bonus: Screenshots without theme variants

For diagrams or architecture images that don't need dark mode:

{{ heroshot_single("architecture", "System architecture") }}

Renders a simple <img> tag.

Full docs: heroshot.sh/docs/integrations/mkdocs

Example repo: github.com/omachala/heroshot/tree/main/integrations/examples/mkdocs