Produkt-Screenshots automatisch erstellen: Anleitung für Ihre Doku
Sie haben eine Schaltfläche verschoben. Jetzt zeigen 14 Hilfeartikel das alte Layout, und jemand muss sich anmelden, das richtige Demo-Konto finden, das Fenster anpassen und jedes Bild neu aufnehmen. Niemand will diese Aufgabe, also bleibt sie liegen, und die Dokumentation beginnt stillschweigend zu lügen.
Die Lösung ist, Produkt-Screenshots nicht mehr von Hand aufzunehmen. Um Produkt-Screenshots automatisch zu erstellen, schreiben Sie ein Skript, das sich in ein vorbereitetes Demo-Konto einloggt, jede Seite in einem Headless-Browser mit fester Größe aufruft, gezielt einzelne Elemente (nicht den ganzen Bildschirm) in doppelter Auflösung aufnimmt, alles maskiert, was sich zwischen den Läufen ändert, und jedes Bild unter einem stabilen Dateinamen speichert. Dann führen Sie das Skript in der CI aus, sobald sich die Oberfläche ändert. Playwright erledigt das alles mit etwa 60 Zeilen.
Unten finden Sie das Skript, das wir tatsächlich verwenden würden, die Details, die das Ergebnis konsistent machen, und die Teile, die weiterhin einen Menschen brauchen.
Warum manuelle Produkt-Screenshots veralten
Screenshots von Hand scheitern aus banalen Gründen:
- Sie sind aufwendig zu wiederholen, also schiebt man es auf. Ein Redesign, das die Seitenleiste berührt, kann auf einen Schlag jedes Bild in Ihrem Help-Center ungültig machen.
- Sie sind uneinheitlich. Einer wurde auf einem 13-Zoll-Laptop aufgenommen, einer auf einem 4K-Monitor, einer im Dark Mode, einer mit dem Symbol einer Browser-Erweiterung in der Ecke.
- Sie geben echte Daten preis. Der echte Posteingang von jemandem, ein Kundenname, eine echte E-Mail-Adresse im Avatar-Menü.
- Niemand weiß, welche veraltet sind. Es gibt keine Verbindung zwischen „Wir haben die Abrechnungsseite geändert“ und „Diese fünf Bilder zeigen die Abrechnungsseite“.
Screenshot-Automatisierung löst die ersten drei Probleme vollständig und gibt Ihnen beim vierten eine Chance. Wenn Ihre Dokumentation insgesamt veraltet (nicht nur die Bilder), behandelt Dokumentation aktuell halten, wenn Sie jede Woche ausliefern die größere Fassung dieses Problems.
Was Sie brauchen, bevor Sie Code schreiben
Drei Dinge lassen automatische Dokumentations-Screenshots funktionieren. Lassen Sie eines weg, bekommen Sie wackelige, hässliche Ergebnisse.
1. Ein vorbereitetes Demo-Konto
Ihr Skript muss sich in ein Konto einloggen, das immer gleich aussieht: derselbe Firmenname, dieselben 12 Projekte, dieselben erfundenen Kollegen mit glaubwürdigen Namen. Schreiben Sie ein Seed-Skript (scripts/seed-demo.ts oder was zu Ihrem Stack passt), das dieses Konto löscht und neu anlegt. Realismus zählt. Ein Dashboard voller „Test Project 1“ und „asdf“ wirkt in einem Hilfeartikel kaputt.
2. Stabile Selektoren für das, was Sie aufnehmen
Sie fotografieren Elemente, also brauchen Sie einen verlässlichen Weg, sie zu finden. CSS-Klassen aus Tailwind oder CSS-in-JS ändern sich ständig. Fügen Sie stattdessen ein eigenes Attribut hinzu:
<section data-docs="billing-summary">...</section>
Es kostet nichts, übersteht Refactorings und sagt jedem Entwickler: „Dieses Element taucht in der Doku auf, denk nach, bevor du es löschst.“
3. Eine Shot-Liste
Eine einfache Liste jedes Bildes, das Ihre Dokumentation verwendet: welche Seite, welches Element, was maskiert wird und der Name der Ausgabedatei. Halten Sie sie im Code, neben dem Skript. Diese Liste ist später auch Ihre Antwort auf die Frage „Welche Screenshots zeigen die Abrechnungsseite?“.
Ein funktionierendes Playwright-Screenshot-Skript
Playwright ist dafür heute das beste Werkzeug. Es steuert echtes Chromium, Firefox oder WebKit, kann ein einzelnes Element aufnehmen und hat eingebaute Optionen zum Maskieren und zum Einfrieren von Animationen.
Loggen Sie sich zuerst einmal ein und speichern Sie die Sitzung, damit jeder Screenshot-Lauf bereits angemeldet startet:
// scripts/docs-login.mjs
import { chromium } from 'playwright';
const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${BASE_URL}/login`);
await page.getByLabel('Email').fill(process.env.DEMO_EMAIL);
await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: '.auth/demo.json' });
await browser.close();
Dann das eigentliche Screenshot-Skript:
// scripts/docs-screenshots.mjs
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';
const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const OUT_DIR = 'docs/images';
const shots = [
{
name: 'dashboard-overview',
path: '/dashboard',
element: '[data-docs="overview-panel"]',
mask: ['[data-docs="last-synced"]', '[data-docs="avatar"]'],
},
{
name: 'billing-summary',
path: '/settings/billing',
element: '[data-docs="billing-summary"]',
},
{
name: 'invite-teammate-dialog',
path: '/settings/team',
element: '[role="dialog"]',
before: (page) => page.getByRole('button', { name: 'Invite teammate' }).click(),
},
];
const browser = await chromium.launch();
const context = await browser.newContext({
storageState: '.auth/demo.json',
viewport: { width: 1280, height: 800 },
deviceScaleFactor: 2,
colorScheme: 'light',
locale: 'en-US',
timezoneId: 'America/New_York',
reducedMotion: 'reduce',
});
const page = await context.newPage();
// Every "Updated 3 minutes ago" and date picker now shows the same moment.
await page.clock.setFixedTime(new Date('2026-03-02T10:00:00'));
await mkdir(OUT_DIR, { recursive: true });
for (const shot of shots) {
await page.goto(BASE_URL + shot.path);
if (shot.before) await shot.before(page);
const target = page.locator(shot.element);
await target.waitFor({ state: 'visible' });
await target.screenshot({
path: `${OUT_DIR}/${shot.name}.png`,
animations: 'disabled',
caret: 'hide',
mask: (shot.mask ?? []).map((selector) => page.locator(selector)),
maskColor: '#e3d4ff',
// Hide things that should never appear in docs.
style: '#chat-widget, .cookie-banner, .dev-toolbar { display: none !important; }',
});
console.log(`saved ${shot.name}.png`);
}
await browser.close();
Führen Sie es mit node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs gegen Ihre lokale App oder eine Staging-Kopie mit vorbereitetem Demo-Konto aus. Sie erhalten einen Ordner mit gestochen scharfen PNGs, die genau so heißen wie Ihre Shot-Liste.
Die Einstellungen, die Screenshots konsistent machen
Der größte Teil des Nutzens steckt in einer Handvoll Optionen. Hier steht, wozu jede einzelne da ist.
Festes Viewport. 1280x800 sorgt dafür, dass das Layout jedes Mal an denselben Stellen umbricht. Wählen Sie eine Größe und bleiben Sie bei allen Bildern dabei, damit Ihr Help-Center nicht wie eine Collage aussieht.
deviceScaleFactor: 2. Das rendert in Retina-Dichte, sodass ein 600 px breites Element zu einem 1200 px breiten Bild wird. Es sieht auf modernen Laptops und Smartphones scharf aus, und Sie können es im Artikel in halber Größe anzeigen. Die Dateien werden größer. Schicken Sie sie durch einen Optimierer wie oxipng oder wandeln Sie sie in WebP um, wenn Ihnen das wichtig ist.
Element-Screenshots statt ganzer Seiten. Ein Screenshot nur der Karte mit der Abrechnungsübersicht zeigt dem Leser, wohin er schauen soll. Eine Aufnahme der ganzen Seite zwingt ihn zum Suchen. Außerdem berührt eine Änderung an der Seitenleiste Ihr Abrechnungsbild nicht, sodass Sie nur das erneut prüfen, was sich wirklich geändert hat.
Dynamische Inhalte maskieren. Alles, was sich zwischen zwei Läufen ohne Codeänderung unterscheidet, ist Rauschen: relative Zeitstempel, Live-Zähler, „3 Personen online“, zufällige Avatarfarben, ein wechselnder Tipp des Tages. Die Option mask von Playwright legt eine einfarbige Fläche über diese Elemente. Beheben Sie es lieber an der Quelle (vorbereitete Namen, eine eingefrorene Uhr) und maskieren Sie nur, was Sie nicht kontrollieren können.
Eingefrorene Uhr, Locale und Zeitzone. page.clock.setFixedTime fixiert Date.now(), sodass „Fällig in 2 Tagen“ für immer dasselbe sagt. Locale und Zeitzone verhindern, dass ein CI-Runner in einer anderen Region 02/03/2026 statt 3/2/2026 rendert.
Animationen aus, Cursor verborgen. Ein halb fertiges Einblenden oder ein blinkender Cursor taucht in einem Lauf auf und im nächsten nicht.
Die Screenshots in der CI erneut ausführen
Ein Skript, an dessen Ausführung Sie sich erinnern müssen, ist nur wenig besser als Handarbeit. Legen Sie es in die CI.
Die einfachste Variante: Bei jedem Merge in main (oder nachts, wenn Ihre Testsuite langsam ist) starten Sie die App, bereiten das Demo-Konto vor, führen das Skript aus und öffnen einen Pull Request, falls sich ein Bild geändert hat. Git zeigt Bild-Diffs auf GitHub nebeneinander an, sodass ein Prüfer bei „billing-summary.png hat sich geändert“ kurz hinschauen und bestätigen kann, dass die Änderung gewollt ist.
# .github/workflows/docs-screenshots.yml
name: Docs screenshots
on:
push:
branches: [main]
workflow_dispatch:
jobs:
capture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm run seed:demo
- run: npm run start &
- run: npx wait-on http://localhost:3000
- run: node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs
env:
DEMO_EMAIL: ${{ secrets.DOCS_DEMO_EMAIL }}
DEMO_PASSWORD: ${{ secrets.DOCS_DEMO_PASSWORD }}
- uses: peter-evans/create-pull-request@v6
with:
branch: docs/screenshots
title: "Update docs screenshots"
add-paths: docs/images
Eine ehrliche Warnung: Schriften werden unter macOS und Linux leicht unterschiedlich gerendert. Stammen manche Screenshots von Ihrem Laptop und manche aus der CI, „ändern“ sich bei jedem Lauf Bilder, die sich gar nicht wirklich geändert haben. Erzeugen Sie sie nur an einem Ort (in der CI oder lokal mit dem offiziellen Playwright-Docker-Image), und die Diffs bleiben ruhig.
Wo Screenshots per Skript noch an Grenzen stoßen
Dieser Ansatz ist großartig, und er bleibt trotzdem Arbeit. Seien Sie realistisch:
- Jemand muss die Shot-Liste pflegen. Kommt eine Funktion hinzu, muss jemand ihre Screenshots ergänzen, die Selektoren schreiben und entscheiden, was maskiert wird. Fällt eine Seite weg, schlägt das Skript fehl, bis jemand den Eintrag entfernt.
- Es weiß nicht, wo Bilder hingehören. Das Skript aktualisiert
billing-summary.png. Es weiß nicht, welche Artikel es verwenden oder ob die Schritte drumherum noch stimmen. - Die Authentifizierung wird fummelig. Logins nur per SSO, Magic Links, 2FA und OAuth-Verbindungen zu Drittdiensten brauchen alle Umwege (eine Login-Route nur für Tests ist die übliche Antwort).
- Es erfasst Zustände, keine Geschichten. Ein mehrstufiger Ablauf lässt sich besser als kurzes Video zeigen. Das behandeln wir in Produkt-Walkthrough-Videos erstellen.
Es gibt weitere Optionen. Cypress hat cy.screenshot() und funktioniert gut, wenn Ihr Team ohnehin in Cypress zu Hause ist. Puppeteer arbeitet auf niedrigerer Ebene und ist auf Chromium ausgerichtet. shot-scraper ist ein praktischer CLI-Wrapper um Playwright, wenn Sie lieber eine YAML-Datei als ein Skript pflegen. Für einzelne Marketing-Aufnahmen ist ein manuelles Tool wie CleanShot X mit einer einheitlichen Fenstergröße ehrlich gesagt in Ordnung. Der Weg per Skript lohnt sich, wenn Sie mehr als ein paar Dutzend Bilder aktuell halten müssen.
Screenshots automatisieren, ohne das Skript zu schreiben
Das ist der Teil der Arbeit, den Ellie Docs Ihnen abnehmen soll. Sie verbinden ein GitHub-Repository, und Ellie liest den Code, um Ihre Funktionen und nutzersichtbaren Seiten zu erfassen. Dann startet es Ihre App in einer Sandbox, meldet sich als Testnutzer an und nimmt echte Screenshots des angemeldeten Produkts auf, die direkt in die Hilfeartikel eingefügt werden, die es entwirft.

Weil jeder Artikel mit den Funktionen verknüpft ist, die er beschreibt, wird ein gemergter PR, der eine dieser Funktionen ändert, bei den richtigen Artikeln markiert, und Sie prüfen den vorgeschlagenen Eintrag, bevor etwas live geht. Sie pflegen keine Shot-Liste und keine Selektor-Datei.

Wenn Sie das Playwright-Skript gern selbst besitzen, behalten Sie es. Es ist ein gutes Setup. Wenn Sie lieber hätten, dass die Screenshots, die Artikel drumherum und die laufende Pflege für Sie erledigt werden, ist genau das, was Ellie tut. Auch die Worte rund um diese Bilder zu schreiben ist ein eigenes Handwerk. Siehe Hilfeartikel schreiben, die Menschen wirklich nutzen.
Häufige Fragen
Welche Auflösung sollten Dokumentations-Screenshots haben?
Nehmen Sie in doppelter Auflösung (deviceScaleFactor: 2) aus einem festen Viewport von etwa 1280 Pixeln Breite auf und zeigen Sie in halber Größe an. So erhalten Sie scharfe Bilder auf Retina-Bildschirmen, ohne riesige Layouts.
Sollte ich die ganze Seite aufnehmen oder nur einen Teil? Meist nur einen Teil. Schneiden Sie auf das Element zu, um das es im Schritt geht, mit etwas Umgebung, damit der Leser es findet. Nutzen Sie Aufnahmen ganzer Seiten sparsam, für Momente wie „Das ist das Gesamtlayout“.
Wie halte ich echte Kundendaten aus Screenshots heraus?
Nehmen Sie nie aus Produktionskonten auf. Verwenden Sie ein vorbereitetes Demo-Konto mit erfundenen Namen und example.com-E-Mail-Adressen und maskieren Sie, was Sie nicht vorbereiten können, etwa Widgets von Drittanbietern.
Wie oft sollten automatische Screenshots laufen? Bei jedem Merge in main, wenn der Lauf schnell ist, nachts, wenn nicht. Der Sinn ist, dass sich niemand erinnern muss.
Wenn Sie das alles erledigt haben möchten, testen Sie Ellie Docs kostenlos. Verbinden Sie ein Repository, und Sie erhalten ein Help-Center mit echten Screenshots Ihrer App, ohne Karte.