Ondrej Machala

Posted on Jan 29

Keep Your MkDocs Screenshots Up to Date (Material Theme)

#python #documentation #mkdocs #webdev

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

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

pip install heroshot

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

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:

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.

When your UI changes:

heroshot

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

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

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

Renders a simple <img> tag.