---
title: Das Handbuch pflegen
description: Pflicht zum Mitschreiben, Seiten schreiben, Screenshots, lokal ansehen und bauen.
---

Das Handbuch liegt in `handbuch/` und wird mit [Blume](https://useblume.dev) gebaut.

:::warning[Pflicht bei jeder Änderung]
Jeder Merge Request, der Verhalten, Oberfläche, Rechte, Betrieb oder den Entwicklungsablauf
ändert, prüft die betroffenen Handbuchseiten und überarbeitet sie **im selben Merge Request**.
Neue Funktionen bekommen ihre Seite oder ihren Abschnitt, geänderte Oberflächen aktuelle
Screenshots. Gibt es keinen Handbuch-Bedarf, steht die Begründung im Merge Request. Die
MR-Vorlage fragt das ab.
:::

## Lokal ansehen

```bash
cd handbuch
npm install
npm run dev
```

Vor dem Commit:

```bash
npm run build        # bricht bei kaputtem Frontmatter oder MDX ab
npx blume validate   # prüft alle internen Links
```

Im Dev-Stack läuft das gebaute Handbuch unter https://handbuch.localhost.

## Abhängigkeiten

Renovate hält Blume und das nginx-Image aktuell. Updates fürs Handbuch tragen das Label
`handbuch`; Minor- und Patch-Updates kommen gebündelt in einem Merge Request „Handbuch
dependencies“, Sicherheitsupdates in „Handbuch Vulnerability Alerts“. `test:handbuch` baut jedes
Update streng. Das npm-Override für `path-to-regexp` in `package.json` schließt eine Lücke im
ungenutzten Vercel-Adapter von Blume; es kann weg, sobald Blume es nicht mehr braucht.

:::warning[Override `@astrojs/react` bei jedem Blume-Update prüfen]
`package.json` hält `@astrojs/react` per Override auf `7.0.1`, Renovate hebt es nicht an. Blume
pinnt `@vitejs/plugin-react` exakt auf 6.1.1, `@astrojs/react` ab 7.1.0 verlangt eine höhere
Version; ohne Override bleibt `npm install` ohne Lockfile endlos in der Abhängigkeitsauflösung
hängen. Bei jedem Blume-Update prüfen, ob Blumes Pin zu einem aktuellen `@astrojs/react` passt:
Override entfernen, Lockfile löschen, `npm install` und `npm run build` laufen lassen. Klappt das,
fliegt der Override samt Renovate-Regel raus, sonst bleibt er.
:::

:::warning[Kein `npm audit fix --force`]
Der Befehl setzt `blume` auf den Platzhalter 0.0.0 und leert damit das Lockfile. Die Meldungen von
`npm audit` stammen aus Blumes Abhängigkeiten; einzelne Lücken schließt ein gezieltes Override.
:::

## Aufbau

```txt
handbuch/
  blume.config.ts       Titel, Tabs, Sprache
  inhalt/
    index.mdx           Startseite
    anwender/           Tab „Anwender“
    administration/     Tab „Administration“
    entwicklung/        Tab „Entwicklung“
```

Jeder Ordner ist eine Gruppe in der Seitenleiste. Nummernpräfixe wie `02-` bestimmen die
Reihenfolge der Gruppen und fallen in der URL weg: `anwender/02-einsaetze/einsatz-anlegen.mdx`
wird zu `/anwender/einsaetze/einsatz-anlegen`. Die Reihenfolge der Seiten in einer Gruppe steht
in deren `meta.ts` (`pages`). Eine neue Seite gehört dort eingetragen. Einzelne Themen auf
oberster Ebene liegen als Ordner mit `index.mdx`, sonst rutschen sie in der Seitenleiste über
alle Gruppen.

## Schreibregeln

- Das Produkt heißt im Text immer **Lagewerk**; `elw` taucht nur in technischen Bezeichnern
  auf (Pfade, Hostnamen, Container).
- Anrede „Sie“, sachlich und knapp. Begriffe, Knöpfe und Menüs exakt wie in der Oberfläche, in
  **Fettschrift**.
- Nur beschreiben, was umgesetzt ist. Spez und Code können abweichen, dann gilt der Code.
- Im Anwender-Teil keine API-Pfade, Tabellennamen oder Permission-Keys; Rechte heißen so wie in
  der Rollenverwaltung.
- Fachliche Regeln (was wann nicht geht, was automatisch passiert) gehören hinein, sie sind das
  Wertvollste am Handbuch.
- Frontmatter-Werte mit „: “ in Anführungszeichen setzen.
- Komponenten wie `<Steps>`, `<Card>` und Hinweise mit `:::note` brauchen keinen Import.
  Übersicht: [Blume-Komponenten](https://useblume.dev/docs/content/components).

## Screenshots

Screenshots machen Abläufe schneller verständlich. Sie veralten aber mit jeder Änderung an der
Oberfläche und werden deshalb im selben Merge Request erneuert.

- **Ablage:** neben der Seite in einem Ordner `bilder/`, zum Beispiel
  `anwender/02-einsaetze/bilder/einsatz-anlegen-formular.png`. Eingebunden relativ:
  `![Formular Einsatzdaten](./bilder/einsatz-anlegen-formular.png)`. Blume optimiert die
  Bilder beim Bauen.
- **Aufnahme:** gegen den Dev-Stack (https://elw.localhost) mit Testdaten, nie mit echten
  Patientendaten. Helles Farbschema, Fensterbreite 1440 px, nur der relevante Ausschnitt.
  Playwright eignet sich für wiederholbare Aufnahmen.
- **Alternativtext** beschreibt, was zu sehen ist.
- Ein Screenshot ersetzt keine Beschreibung: Regeln und Schritte stehen weiter im Text.

## Diagramme

Abläufe und Strukturen als Mermaid-Codeblock direkt in der Seite. Frei gelayoutete Diagramme als
`.drawio.svg` in `bilder/`: Die Datei ist ein normales Bild für Blume und lässt sich zugleich in
draw.io öffnen und bearbeiten (Desktop, Web oder VS-Code-Erweiterung). Eine `.excalidraw`-Fassung
daneben ist erlaubt, eingebunden wird das SVG. Nach dem Bearbeiten als `.drawio.svg` speichern,
nicht als reines SVG, sonst gehen die Diagrammdaten verloren. Blume meldet dazu beim Bauen
`BLUME_SVG_UNOPTIMIZED`: Die eingebetteten Diagrammdaten verdecken die Bildgröße, das Bild wird
unverändert ausgeliefert. Das ist gewollt und harmlos.

Die Diagramme auf Entwicklung › Architektur entstehen per Skript aus einem gemeinsamen Modell
(`scripts/diagramme/`, Aufruf `python3 scripts/diagramme/erzeugen.py`). Für sie ist das Skript die
Quelle: Änderungen dort eintragen und neu erzeugen, nicht in draw.io oder Excalidraw. Angezeigt
werden Excalidraw-Exporte in Hell und Dunkel (`<name>.excalidraw.svg`, `<name>.excalidraw.dark.svg`);
sie werden nach jedem Lauf von Hand aus der neuen `.excalidraw` exportiert (Anleitung in
`scripts/diagramme/README.md`). Die Seite bindet beide per Import ein und schaltet mit den Klassen
`dark:hidden` und `hidden dark:inline-flex` um.
