Forem: Ondrej Machala

What's New in Diction 5.0

Ondrej Machala — Tue, 14 Apr 2026 21:18:46 +0000

Diction 5.0 is out. Three things changed in a meaningful way: the cloud is rebuilt from scratch, AI Companion can now edit text by voice, and the app is fully localized in 13 languages. Everything else is polish on top of that foundation.

Diction One is a different thing now

I spent several weeks working with physical hardware for this. Dedicated speech models for each language family, better audio processing, faster response across the board. If you tried cloud mode in an earlier version and found it slow or inaccurate, I'd ask you to try it again.

The mic is always warm now. Tap and start talking immediately. No noticeable gap between the button and your voice.

Your voice can now edit

AI Companion in v4 could clean up what you said. In v5, it can edit what's already written.

You're writing an email. You wrote "let's meet Tuesday" but the meeting moved. Place your cursor anywhere in that sentence and say "change Tuesday to Thursday." No selecting, no deleting, no retyping.

Or select a paragraph that's too stiff and say "make this more casual." Diction rewrites the selection. The action bar turns indigo when text is selected so you always know what mode you're in.

Long-press the action bar to rewrite text around your cursor without selecting anything first. Say what's wrong, Diction fixes it.

13 languages, properly localized

Every screen now adapts to your system language: Settings, History, Insights, everything. Switch the UI language live from the picker without restarting the keyboard.

Before this release, everyone got English regardless of what their iPhone was set to.

Other changes worth knowing

Insights is redesigned. Your typing speed multiplier is the main number, with daily average, words per minute, days used, and time saved all visible at once.

New mic release options. "After dictation" drops the mic the moment the transcription finishes. Ten-second and 30-second options for music and podcast listeners.

AirPods work correctly now. Music stays in stereo while Diction uses the built-in mic. Nothing ducks.

AI Companion is smarter about keeping your voice. It preserves natural speech patterns, writes numbers as digits, and doesn't drop sentences on longer recordings.

For self-hosters: support for bringing your own language model for AI Companion, a one-command setup covering 25 European languages, and smart routing that picks the right speech model per language with a health-checked fallback. Open source at github.com/omachala/diction.

Diction 5.0 is on the App Store now: https://apps.apple.com/app/id6759807364

How Diction handles privacy

Ondrej Machala — Thu, 02 Apr 2026 09:00:00 +0000

Voice keyboards sit in an uncomfortable position. Every app you use, every message you send, every search you type — the keyboard is there. It sees all of it.

Most people install a keyboard and never think about this. I did, because I was building one.

Earlier this year, someone reverse-engineered a popular voice keyboard and posted their findings. The app was collecting full browser URLs, names of focused apps, on-screen text scraped via the Accessibility API, clipboard contents including data copied from password managers, and sending it all back to a server. There was a function in the binary called sendTrackResultToServer. None of this was in the privacy policy.

This is not a hypothetical. It happened. And the only reason anyone found out is because the app was installed on a machine where someone was curious enough to look.

That is the problem with closed-source software and privileged access: you cannot verify the claims. A privacy policy is a document. The code is what runs.

Full Access and what it actually enables

When iOS asks if you want to allow Full Access for a keyboard, the permission is broader than most people realise. It enables network access (how keyboards send audio for transcription or sync dictionaries). But in the wrong hands it also means the keyboard code runs in a context where it could read clipboard data, monitor app usage patterns, or transmit information alongside its legitimate function.

Diction has no QWERTY keys. There is nothing to type into it, so nothing to log in that sense. But I wanted to go further than just "we don't do the bad thing." I wanted to build it so you can verify we don't.

How I built Diction with this in mind

There are three ways Diction can process your audio, and I picked each one with this threat model in mind.

On-device is the cleanest answer. Your audio never leaves your iPhone. A local speech model handles transcription, the result comes back, and that is it. No server, no transmission, no policy to read. If you want absolute certainty, this is the mode for you.

Self-hosted is for people who want cloud-quality transcription but on infrastructure they control. You point the app at your own server. Your audio goes there and nowhere else. I have no access to what you say or what gets transcribed. The server software is open source. You can read exactly what it does before you run it.

Diction One is the hosted cloud option. Here I had to think carefully. Audio is processed in memory and discarded immediately after transcription. Nothing is written to disk. No transcriptions are stored or logged. And every transcription is encrypted with AES-256-GCM using a fresh X25519 key per request. The same standards WireGuard uses. I am not asking you to trust the policy. The implementation is in the open-source server code.

The app itself

The Diction app contains no analytics and no tracking code. No device identifiers, no usage events, no behavioural monitoring. The App Store privacy label reads "Data Not Collected." I can say that confidently because I wrote every line and there is nothing there.

What you can actually verify

The server code is public at github.com/omachala/diction. You can read the transcription handler and confirm that audio is not written anywhere. You can read the encryption implementation. If you run on-device mode, you can point a network inspector at the app and confirm no requests leave it.

I built it this way because I wanted to use this keyboard myself. And I was not willing to just trust a policy page written by someone else.

Download on the App Store · diction.one/privacy-first

What's New in Diction 4.0

Ondrej Machala — Wed, 01 Apr 2026 15:04:42 +0000

Diction 4.0 is the biggest update since launch. The theme is straightforward: do more with your voice, with fewer rough edges. This release took hundreds of commits and more testing rounds than I want to count. Here is what landed.

Speak to Edit

This is the headline feature. Select any text in any app, tap the mic, and say what you want changed.

You are editing an email. You select "Wednesday works for me" and say "Thursday actually." Diction replaces the selection.

It also handles instructions. Select a paragraph and say "translate to Czech." Or "make this shorter." Or "more formal." Diction figures out whether you are giving a literal replacement or an editing instruction and acts accordingly.

Before this, voice keyboards were append-only. You could dictate new text, but editing meant switching to the regular keyboard. Now you stay in voice the whole time.

Custom Words Improve Transcription Directly

In 3.0, custom words (My Words) only helped during AI Enhancement cleanup. Now they feed directly into the speech model as vocabulary hints.

Your coworker's name is Kaelith. Your product is called Nexaro. You added both to My Words. Now the raw transcription gets them right on the first pass, even with AI Enhancement turned off.

This matters most for anyone dictating technical terms, brand names, or anything the base model has never seen.

Long Recordings That Actually Finish

Previous versions could cut off or lose the end of longer dictations. 4.0 rewrites the recording pipeline to handle long sessions without dropping audio.

If you are dictating meeting notes, a long email, or journal entries, the transcript comes back complete.

Profile

Tell Diction who you are and how you write. "I'm a software engineer. I write in short, direct sentences. I use American English."

AI Enhancement uses your profile to match your style. Instead of generic cleanup, it produces text that sounds like you actually wrote it. The profile persists across all your dictations, so you set it once.

Guided Onboarding

First launch used to throw permission dialogs at you and hope you figured it out. Now there is a step-by-step walkthrough: keyboard installation, permissions, first dictation. You know exactly where you are and what to do next.

Better On-Device Setup

Downloading speech models should not be confusing. The download flow is smoother now, preparation is faster, and the model is ready to use as soon as it finishes. No extra steps.

No More Phantom Orange Dot

Opening the Diction app used to activate the microphone, which lit up the iOS orange dot even though you were not dictating. Fixed. The mic only activates when you actually start a dictation.

Under the Hood

AI Enhancement accuracy improved across apps
UI polish across the keyboard, history, tones, and settings
Stability improvements throughout. 4.0 is a significantly more stable release than 3.0.

Diction is a voice keyboard for iPhone. Tap the mic, speak, text appears wherever your cursor is. On-device, cloud, or self-hosted.

App Store / GitHub / Website

I Use NanoClaw in Telegram All Day. I Stopped Typing to It.

Ondrej Machala — Sat, 28 Mar 2026 09:00:00 +0000

I have NanoClaw connected to my Telegram. Throughout the day I send it things. Translate this. Summarise that article. What time is it in Tokyo. Draft a reply to this message. It responds in the same thread, without me leaving the app.

It runs on my own machine, inside a container. The agent only has access to what you explicitly give it. Setup took about fifteen minutes: clone the repo, run Claude Code, type /setup.

What I didn't anticipate: I was still typing everything. Long questions. Multi-sentence requests. Context I had to spell out carefully. The assistant was right there in Telegram, but slow input was still slowing me down.

Where Diction comes in

I built Diction to fix exactly this. It's an iOS keyboard extension. In Telegram, you switch to it, tap the mic, speak, and the text appears in the compose field. Send it like any message.

I dictate to NanoClaw now. "Can you draft a short reply to this email, keep it friendly but firm." Things that would take a minute to type take ten seconds to say. NanoClaw gets the same message either way.

Diction has an on-device mode that runs locally on your iPhone. Nothing leaves the device. For a setup where the whole point is keeping your data on your own hardware, that felt like the right match.

The setup, end to end

NanoClaw:

Clone github.com/qwibitai/nanoclaw
Run Claude Code in the repo directory
Type /setup — Claude Code handles everything
Connect your Telegram bot token when prompted

Diction:

Install from the App Store
Settings → General → Keyboard → Add New Keyboard → Diction
Switch to it in Telegram, tap the mic

That's the whole stack. A personal assistant on your own hardware, voice input on your own device.

NanoClaw on GitHub | Diction on the App Store

Self-Host Speech-to-Text and Use It as Your iPhone Keyboard in 3 Commands

Ondrej Machala — Thu, 26 Mar 2026 09:00:00 +0000

If you're running a homelab, you've probably already got speech-to-text somewhere in your stack.

Maybe you use it for Home Assistant voice commands. Or local LLM integrations. Or just transcribing meeting recordings.

Here's something you might not have considered: you can use that same transcription server as a keyboard on your iPhone.

The 3 Commands

git clone https://github.com/omachala/diction
cd diction
docker compose up -d

That's the server running. Now install Diction on your iPhone, point it at your server URL, and you have a voice keyboard backed by your own speech-to-text instance.

What's Actually Running

The Docker Compose setup spins up two services:

services:
  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    ports:
      - "8080:8080"

  whisper-small:
    image: fedirz/faster-whisper-server:latest-cpu
    environment:
      WHISPER__MODEL: Systran/faster-whisper-small
      WHISPER__INFERENCE_DEVICE: cpu

whisper-small: the transcription engine — runs open-source Whisper via a REST API. CPU works fine for real-time dictation.

gateway: a small open-source Go service that handles communication between the iOS app and the transcription backend. It accepts WebSocket connections from the phone, buffers audio frames, and forwards them to Whisper. This is what makes dictation feel instant instead of "record, upload, wait."

The gateway exposes port 8080. That's the URL you put into the Diction app.

Making It Accessible From Your Phone

Your phone needs to reach your server. A few options depending on your setup:

Tailscale (easiest): Install Tailscale on both your server and iPhone. You get a private IP accessible from anywhere. No port forwarding, no firewall rules.

http://100.x.x.x:8080

Reverse proxy (for existing homelabbers): If you're already running Caddy, nginx, or Traefik, add a route to port 8080.

https://diction.yourdomain.com

Direct LAN (simplest for home-only use): Just use your server's local IP. Works on home WiFi, not outside.

http://192.168.1.100:8080

Choosing a Model

Swap the transcription model by changing WHISPER__MODEL. The model downloads automatically on first use.

Size	RAM	Speed (CPU)	Notes
Tiny	~350MB	~1-2s	Lower accuracy, great for low-power hardware
Small	~800MB	~3-4s	Good default for everyday dictation
Medium	~1.8GB	~8-12s	Better with accents and background noise
Large	~3.5GB	~20-30s	Highest accuracy, benefits from GPU

For most home servers, the small model hits the sweet spot — fast enough to feel real-time, accurate enough for messages and notes.

Swap it in your compose file:

  whisper-small:
    image: fedirz/faster-whisper-server:latest-cpu
    environment:
      WHISPER__MODEL: Systran/faster-whisper-medium
      WHISPER__INFERENCE_DEVICE: cpu

Running on Lower-Power Hardware

The small model runs well on modern CPUs. For a NAS or Raspberry Pi, try tiny — less RAM (~350MB), faster responses, some accuracy trade-off. For real-time keyboard use, aim for sub-3 second round-trip. Small on a modern CPU or tiny on lower-power hardware gets you there.

Already Running a Whisper Server?

If you already have a speech-to-text container running, you don't need to spin up another one. Just run the gateway and point it at your existing server:

services:
  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    ports:
      - "8080:8080"
    environment:
      CUSTOM_BACKEND_URL: http://your-server:8000
      CUSTOM_BACKEND_MODEL: your-model-name

More details on connecting to existing servers in this post.

The server and gateway are fully open source: github.com/omachala/diction

You Already Have a Speech Server. Your iPhone Keyboard Should Use It.

Ondrej Machala — Wed, 18 Mar 2026 09:36:35 +0000

Someone posted on our GitHub Discussions this week. They'd been running a speech-to-text container on their homelab for months. Found Diction, an open-source iOS voice keyboard. Pointed the app at their server. Got a server error. The settings screen even said "endpoint reachable."

Here's what was going wrong, and how two lines of config fixes it.

Why direct connection fails

Diction doesn't talk directly to speech servers. It connects through a lightweight gateway first.

The reason is WebSockets. When you tap the mic, the app opens a WebSocket and streams raw PCM audio to the gateway in real time as you speak. When you're done, the gateway POSTs the full audio to your speech server, gets the transcript, and sends it back. The whole exchange happens in the time it takes to stop speaking.

Without this, the alternative is: record the whole thing, send a file, wait. You'd feel every pause. The WebSocket is what makes it feel instant.

The "endpoint reachable" check passes because the iOS app pings /health or /v1/models. Most speech servers expose these. But the actual transcription uses the WebSocket endpoint, which only the gateway handles. No gateway, no streaming.

The fix

You don't need to run our speech containers. Just the gateway, pointed at yours.

If your server is at http://192.168.1.50:8000, this is your entire docker-compose.yml:

services:
  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    ports:
      - "8080:8080"
    environment:
      CUSTOM_BACKEND_URL: http://192.168.1.50:8000
      CUSTOM_BACKEND_MODEL: your-model-name-here

Start it:

docker compose up -d

Open Diction, go to Self-Hosted, paste http://192.168.1.50:8080. Done.

Your model stays where it is. The gateway handles the WebSocket layer, audio buffering, and forwarding. Audio still only goes to your server.

CUSTOM_BACKEND_MODEL

One thing to get right: the model name.

Most speech servers that follow the OpenAI-compatible API format expect a model field in the transcription request to know which model to load. Without it, some return an error.

Set CUSTOM_BACKEND_MODEL to whatever name your server expects. Check your server's docs or the model you started it with. If your server only runs one model and ignores the field, you can omit it entirely.

WAV-only servers

Some speech servers only accept WAV audio input. The gateway handles conversion automatically:

environment:
  CUSTOM_BACKEND_URL: http://192.168.1.50:5092
  CUSTOM_BACKEND_NEEDS_WAV: "true"

With this set, the gateway converts audio to 16kHz mono WAV via ffmpeg before forwarding. Your server gets the format it expects.

API key protection

If your server is behind an API key:

environment:
  CUSTOM_BACKEND_URL: http://my-server:8000
  CUSTOM_BACKEND_MODEL: my-model
  CUSTOM_BACKEND_AUTH: "Bearer sk-your-key"

The gateway injects the Authorization header on every request to your backend.

Latency on a local network

I tested this end-to-end: generated a speech WAV, sent it through the gateway to a real speech container, got the transcript back correctly. On a local network with a CPU-only container, the round trip was under 5 seconds. With a dedicated GPU, it's near instant.

What the gateway actually does

The gateway is open source at github.com/omachala/diction. It's a small Go service that:

Accepts WebSocket connections from the iOS app
Buffers incoming PCM audio frames
Wraps them in a WAV header and POSTs to your speech backend
Returns the transcript over the WebSocket

No cloud calls. No telemetry. The full source is in /gateway/core/.

If you're running a Whisper server and want to get started from scratch, the 3-command setup guide covers the full stack.

You Wrote 14 Playwright Scripts Just to Screenshot Your Own App

Ondrej Machala — Tue, 17 Mar 2026 14:00:00 +0000

It started simple. One Playwright script to capture the homepage.

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://myapp.com');
await page.screenshot({ path: 'homepage.png' });
await browser.close();

Then the team needed the pricing page. So I added another script. Then the dashboard (which needs login first). Then the settings page (which needs a specific tab clicked). Then mobile versions.

Two months later I had 14 Playwright scripts. Some shared a login helper. Some had hardcoded waits. One had a try-catch that silently swallowed errors because the cookie banner sometimes loaded and sometimes didn't.

I was maintaining a bespoke test suite, except it wasn't testing anything. It was just taking pictures.

Config, not code

Here's what those 14 scripts look like as config:

{
  "hiddenElements": {
    "myapp.com": [".cookie-banner", ".chat-widget"]
  },
  "screenshots": [
    { "name": "homepage", "url": "https://myapp.com", "selector": ".hero" },
    { "name": "pricing", "url": "https://myapp.com/pricing", "selector": ".pricing-grid" },
    { "name": "dashboard", "url": "https://myapp.com/dashboard", "selector": ".dashboard" },
    {
      "name": "settings",
      "url": "https://myapp.com/settings",
      "selector": ".settings-panel",
      "actions": [
        { "type": "click", "selector": "[data-tab='notifications']" }
      ]
    }
  ]
}

npx heroshot

All 14 screenshots. One command. No scripts to maintain.

The cookie banner problem

In my scripts, I had this pattern everywhere:

try {
  await page.click('.cookie-banner .dismiss', { timeout: 3000 });
} catch { /* maybe it didn't show */ }

With heroshot, you define hidden elements once per domain:

{
  "hiddenElements": {
    "myapp.com": [".cookie-banner"],
    "docs.myapp.com": [".cookie-banner", ".announcement-bar"]
  }
}

Every screenshot on that domain hides those elements automatically. No try-catch. No timeouts. No "maybe it showed, maybe it didn't."

Actions for complex state

The settings page needed a tab clicked first. In Playwright, that's 5 lines of setup. In config:

{
  "actions": [
    { "type": "click", "selector": "[data-tab='notifications']" },
    { "type": "wait", "text": "Email preferences" }
  ]
}

There are 14 action types: click, type, hover, select_option, press_key, drag, wait, navigate, evaluate, fill_form, handle_dialog, file_upload, resize, and hide. Covers pretty much every pre-screenshot setup I've needed.

When to use Playwright directly

If you need complex conditional logic, dynamic data generation, or integration with a test framework, raw Playwright is the right tool.

But if you're just taking pictures of known pages at known states, config is simpler, more readable, and doesn't break when someone renames a helper function.

I Stopped Paying $15/Month for Wispr Flow. Here's the Open-Source Replacement.

Ondrej Machala — Mon, 16 Mar 2026 08:58:03 +0000

I paid for Wispr Flow for five months.

A monthly subscription. Every month. For voice-to-text on my iPhone.

It's a good product. The AI editing layer is genuinely impressive — it strips filler words, fixes grammar, adapts to how you write. That part works. If you want the best cloud-based dictation and don't mind paying, Wispr delivers.

But every time I used it, the same thought: my voice is going to their cloud. Not my cloud. Theirs.

I already run a home server. Docker Compose, Tailscale, the usual homelab stack. I had faster-whisper running for other things. The transcription engine was already there. I just didn't have a way to use it from my phone.

So I built one.

What the switch actually looked like

The server side was easy. I already had the transcription container. I wrote a small Go gateway to handle WebSocket streaming from the phone, and wrapped both in a compose file:

services:
  transcription:
    image: fedirz/faster-whisper-server:latest-cpu
    volumes:
      - models:/root/.cache/huggingface

  gateway:
    image: ghcr.io/omachala/diction-gateway:latest
    ports:
      - "8080:8080"
    environment:
      DEFAULT_MODEL: small
    depends_on:
      - transcription

volumes:
  models:

docker compose up -d and it's running.

The hard part was the iOS keyboard. Keyboard extensions on iOS run in a sandbox with a 48MB memory ceiling, no direct mic access without Full Access, and a text proxy that behaves differently in every app. That took months, not hours.

The result is Diction — a voice keyboard that connects to whatever transcription server you point it at.

What's honestly worse

Wispr's AI editing layer is better than raw transcription. It doesn't just transcribe — it rewrites. Filler words vanish, punctuation lands correctly, and it matches your tone. Diction transcribes what you say. It has optional AI cleanup now, but Wispr's has had years of refinement.

Wispr also has a personal dictionary that learns your vocabulary over time. Diction has custom dictionaries too, but they're newer and simpler.

If you don't want to think about infrastructure and just want the best cloud experience, Wispr is still a strong choice.

What's better

My audio stays on my network. I can verify that because the server code is open source — there's nothing to trust on faith.

No word limits. Wispr's free tier caps you at 1,000 words/week on iOS. Self-hosted Diction has no caps, no subscription, no catch.

Latency on a local network is excellent. The small Whisper model on a modern CPU returns transcriptions in 2-4 seconds. With a GPU, it's near instant.

And when my internet goes down, on-device mode keeps working. Wispr is cloud-only — no connection, no transcription.

The honest trade-off

I traded polish for control. Wispr is more refined. Diction gives me ownership of the entire pipeline, from the mic to the model, and it's getting better with every release.

If you're already running Docker at home and the idea of sending every word you speak to someone else's server bothers you, the self-hosted setup takes about 10 minutes.

github.com/omachala/diction

Astro Docs Without a Single Manual Screenshot

Ondrej Machala — Sat, 14 Mar 2026 14:00:00 +0000

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.

Keep Your MkDocs Screenshots Up to Date (Material Theme)

Ondrej Machala — Thu, 29 Jan 2026 08:51:37 +0000

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

Screenshot Automation in Docusaurus: Getting Started

Ondrej Machala — Tue, 27 Jan 2026 09:28:19 +0000

Docusaurus has dark mode built in. Your docs adapt. Your code blocks adapt. Your screenshots? They just sit there, glaring white on a dark page.

You could maintain two versions of every image and write a custom component to swap them.

Or just automate it.

Heroshot is a CLI that captures screenshots and handles light/dark variants automatically. Here's how to set it up with Docusaurus.

Install

npm install heroshot

Add the plugin

// docusaurus.config.js
const { heroshot } = require('heroshot/plugins/docusaurus');

module.exports = {
  plugins: [heroshot()],
  // ... rest of your config
};

The plugin registers the manifest and sets up the output directory (static/heroshots/ by default).

Capture your first screenshot

Run heroshot:

npx heroshot

A browser opens with a visual picker. Start your Docusaurus dev server in another terminal, navigate to it, and click on the element you want to capture. Name it, close the browser.

You'll get two files:

dashboard-light.png
dashboard-dark.png

Use it in MDX

import { Heroshot } from 'heroshot/docusaurus';

<Heroshot name="dashboard" alt="Dashboard overview" />

The component renders a <picture> element that swaps between light and dark variants based on the user's theme. No flash, no reload.

Update screenshots

When your UI changes, just run npx heroshot again. All configured screenshots regenerate.

That's the basic setup. Once you're running, check out the features article for viewports, retina support, and CI/CD automation.

Docs: heroshot.sh/docs/integrations/docusaurus

heroshot.sh — free, open source.