# Screenshots

> Screenshots automatisch aufnehmen (hell und dunkel), annotieren und nach jedem Deploy aktuell halten.

Screenshots veralten schnell – nach jedem Redesign stimmen die Bilder in der Doku nicht mehr. Docsello löst das mit
**Screenshot-Definitionen**: Du legst einmal fest, *was* aufgenommen wird (Adresse, Ausschnitt, Größe), und Docsello
nimmt das Bild automatisch auf – in hellem und dunklem Farbschema. Seiten binden den Screenshot über einen festen
**Schlüssel** ein. Wird er neu aufgenommen, werden alle Seiten, die ihn verwenden, automatisch neu generiert.

## Screenshot anlegen

:::steps
### Neuer Screenshot

In der Seitenleiste unter **Screenshots** auf **Neuer Screenshot** klicken.

### Schlüssel vergeben

Der **Schlüssel** ist der stabile Name, mit dem Seiten den Screenshot einbinden, z. B. `bestellungen-liste`.
Erlaubt sind Buchstaben, Ziffern, `_`, `.` und `-` (höchstens 100 Zeichen). Er kann später nicht geändert werden.

### Quelle wählen

**Automatisch aufnehmen** oder **Bilder hochladen** (eigene Bilder für hell und optional dunkel).

### Aufnahme einstellen und speichern

Adresse und Optionen festlegen (siehe unten) und **Speichern & aufnehmen** klicken.
:::

## Aufnahme-Optionen

| Option | Bedeutung |
|---|---|
| **URL** | Absolut (`https://…`) oder relativ zur Basis-URL des Aufnahme-Profils (z. B. `/orders?tab=open`) |
| **Aufnahme-Profil** | Liefert Basis-URL, Header, Cookies und Login für interne Apps (siehe unten) |
| **Element (CSS-Selektor)** | Nur dieses Element aufnehmen; leer = ganzer sichtbarer Bereich |
| **Größe** | *Standard (1280×800)* oder eigene Breite und Höhe |
| **Pixeldichte** | 2× liefert scharfe Bilder auf Retina-Displays |
| **Ganze Seite (scrollen)** | Die komplette Seite statt nur des sichtbaren Bereichs |
| **Farbschemata** | Hell und/oder dunkel – über `prefers-color-scheme` (und optional den Profil-Parameter) |
| **Warten auf (Selektor)**, **Verzögerung (ms)** | Erst aufnehmen, wenn ein Element da ist bzw. nach einer Pause |
| **Schritte vor der Aufnahme** | Klicken, Ausfüllen, Hovern, Taste drücken oder Warten – in dieser Reihenfolge |
| **Ausblenden (Selektoren)** | Ein Selektor pro Zeile, z. B. Cookie-Banner, Chat-Widgets, Zeitstempel |
| **Rand um das Element (px)** | Etwas Luft um den aufgenommenen Ausschnitt |

In der Liste zeigt Docsello für jeden Screenshot den Status, die letzte Aufnahme, auf welchen Seiten er verwendet wird
und wie stark sich die letzte Aufnahme von der vorherigen unterscheidet (*unverändert*, *kleine Änderung*,
*Änderung*, *große Änderung*).

## Aufnahme-Profile für interne Anwendungen

Unter **Aufnahme-Profile** hinterlegst du für Anwendungen hinter einem Login:

- **Basis-URL** – relative Screenshot-URLs werden daran angehängt.
- **Header** und **Cookies** – z. B. ein Zugangstoken. Als *geheim* markierte Werte werden nach dem Speichern nie wieder
  angezeigt.
- **Login-Schritte** – laufen einmal vor den Aufnahmen (z. B. Benutzername und Passwort ausfüllen, auf „Anmelden“
  klicken). Die Sitzung wird für hell und dunkel wiederverwendet. Optional mit eigener **Login-URL**.
- **Farbschema-Parameter** – hängt z. B. `?theme=dark` an die URL, für Apps, die `prefers-color-scheme` ignorieren.

Ohne Profil sind nur öffentliche, absolute URLs möglich.

## In Seiten einbinden

Im Editor über `/screenshot`, oder in Markdown:

```markdown
::screenshot{key="bestellungen-liste" alt="Bestellübersicht mit drei offenen Bestellungen" caption="Die Bestellübersicht"}
```

Auf der Website wird automatisch das passende Bild zum hellen oder dunklen Farbschema des Lesers gezeigt. Die
Detailseite eines Screenshots zeigt unter **In Seiten einbinden** das fertige Snippet zum Kopieren.

## Annotieren

Mit **Annotieren** öffnest du den Annotations-Editor. Die Werkzeuge:

| Werkzeug | Wirkung |
|---|---|
| **Pfeil** | Pfeil mit optionaler Beschriftung |
| **Rahmen** | Rechteck um einen Bereich |
| **Nummer** | Nummerierte Markierung, z. B. für Schritt-für-Schritt-Anleitungen |
| **Unkenntlich** | Verpixelt den Bereich dauerhaft im gerenderten Bild – für persönliche Daten |
| **Hervorheben** | Dunkelt alles außer diesem Bereich ab |
| **Zuschneiden** | Wird zuletzt angewendet – alles außerhalb fällt weg |

Annotationen gelten für hell und dunkel und bleiben bei jeder Neuaufnahme erhalten – das Originalbild wird nie
verändert. Mit **Annotationen speichern** wird das Ergebnis neu gerendert.

## Neu aufnehmen – auch aus der CI

In der Liste nimmst du einzelne Screenshots mit **Neu aufnehmen** oder alle mit **Alle neu aufnehmen** neu auf.
Sinnvoller ist es, das nach jedem Deploy deiner Anwendung automatisch zu tun – mit einem API-Token mit dem Recht
*Bearbeiten & veröffentlichen*:

::::tabs{sync="werkzeug"}
:::tab{title="CLI"}
```bash
docsello screenshots capture --all
docsello screenshots capture --key bestellungen-liste --key einstellungen
```
:::
:::tab{title="HTTP"}
```bash
curl -X POST "$DOCSELLO_URL/api/v1/screenshots/capture" \
  -H "Authorization: Bearer $DOCSELLO_TOKEN" -H "content-type: application/json" \
  -d '{"all": true}'
```
:::
::::

Screenshots lassen sich auch per API definieren (`PUT /api/v1/screenshots/<schlüssel>`) und von KI-Agenten über den
[MCP-Server](doc:mcp-server) anlegen und neu aufnehmen.