# Vom Markdown-Report zur Website URL: https://www.mikebild.dev/de/blog/vom-markdown-report-zur-website/ Ein Live-Dashboard und ein Bericht beantworten verschiedene Fragen. Das Dashboard zeigt, was gerade geschieht. Der Bericht hält fest, welcher Stand zu einem bestimmten Zeitpunkt geprüft, besprochen oder freigegeben wurde. Contentkit verbindet den zweiten Fall mit einer Website-Darstellung: Der Report bleibt Markdown, erscheint aber als responsive Seite mit Kennzahlen, Status, Fortschritt und Diagrammen. *Teil 10 der Serie „Contentkit – Publishing für Maschinen“.* Im Beitrag [„Markdown Reports statt Dashboard-Zwang“](https://www.mikebild.dev/de/blog/markdown-reports-statt-dashboard/) habe ich den Report als versioniertes Architekturartefakt beschrieben. Der Kern war der Unterschied zwischen flüchtigem Zustand und festem Nachweis. Damals blieb die Darstellung bewusst einfach. Contentkit nimmt diese Idee auf und löst ein praktisches Problem: Ein prüfbares Textartefakt soll für Entscheider und Anwender nicht wie eine Rohdatei aussehen müssen. ## Bericht und Dashboard nicht gegeneinander ausspielen Eine Betriebsleitstelle braucht aktuelle Latenzen, Fehlerraten und Auslastung. Die Werte ändern sich im Sekundentakt, Interaktion und Alarmierung sind Teil der Aufgabe. Dafür ist ein Live-Dashboard richtig. Ein Quartalsreview braucht etwas anderes. Umsatz, Zielerreichung, Verfügbarkeit, offene Risiken und Entscheidungen sollen den freigegebenen Quartalsstand zeigen. Wenn jemand den Bericht drei Monate später öffnet, dürfen sich die Zahlen nicht still an die Gegenwart angepasst haben. ```mermaid flowchart TD Q{"Welche Frage
soll beantwortet werden?"} Q -->|"Was passiert jetzt?"| L["Live-Dashboard
laufende Daten"] Q -->|"Was galt zum Stichtag?"| R["Markdown-Report
freigegebener Stand"] L --> O["Beobachten und reagieren"] R --> N["Prüfen, vergleichen,
entscheiden und archivieren"] ``` Contentkit nennt die Darstellung Reports und Dashboards, doch die Daten bleiben ein statischer Release-Stand. Das Wort Dashboard beschreibt hier die visuelle Anordnung aus Kennzahlen und Diagrammen, nicht eine dauerhafte Verbindung zu Live-Daten. ## Von der fachlichen Frage zur veröffentlichten Seite Ein Report beginnt nicht mit einem Layout, sondern mit einer fachlichen Frage: Welcher Zeitraum wird betrachtet, welche Entscheidung steht an, welche Evidenz trägt sie? Contentkit behandelt den Report zuerst als nachvollziehbares Dokument. Die visuelle Form wird aus Bedeutung, Frage und Belegen abgeleitet, nicht umgekehrt aus einer Wunschgrafik, für die anschließend Daten gesucht werden. Stand 19. August 2026 gilt im geprüften Repository: Der Autor – ob Mensch oder Agent – schreibt Markdown mit semantischen Blöcken. Eine explizite Narrative ordnet, für wen der Bericht gedacht ist, welche Frage er beantwortet, welche Kernaussage er trägt und welche Handlung daraus folgt. Kennzahlen, Statuskarten, Fortschritt und Diagramme sind Bausteine dieser Narrative, keine freie Visualisierungssprache. Contentkit behandelt solche Reports als semantische Kompositionen und erzeugt daraus responsives HTML sowie eigenständige SVG- und PNG-Repräsentationen derselben Komposition. Im Cockpit verwalten Menschen die unveränderlichen Revisionen und prüfen deren Vorschau. Ein Release veröffentlicht den geprüften Stand, rendert die öffentlichen Routen und wechselt den Site-Zeiger atomar. Für Leser existiert entweder der alte oder der neue Stand – nie ein halb gebauter Zwischenzustand. ## Der Report bleibt die Quelle Ein Contentkit-Report beginnt als Markdown-Seite mit `layout: report`. Kennzahlen und Karten verwenden kontrollierte Direktiven. Diagramme beruhen auf Markdown-Tabellen. Der Release erzeugt daraus statische SVGs, behält die Tabellen aber als zugängliche Belege. ```md --- kind: page layout: report title: Service Review July 2026 locale: en slug: service-review-2026-07 translationKey: service-review-2026-07 summary: Approved snapshot of availability, incidents and actions. date: 2026-07-26 --- ::metric{label="Availability" value="99.93%" trend="Target met" tone="positive"} :::chart{type="line" title="Weekly availability" description="Availability during the final four weeks of July" unit="%"} | Week | Availability | |---|---:| | 26 | 99.91 | | 27 | 99.96 | | 28 | 99.89 | | 29 | 99.98 | ::: ``` Die Markdown-Tabelle ist der Datenvertrag. Ein Reviewer kann Zahlen und Bezeichnungen in der gespeicherten Markdown-Revision prüfen. Der Agent benötigt keine Visualisierungsspezifikation und keinen Chart-Code. Contentkit erzeugt die Darstellung erst beim Build, und die veröffentlichte Seite benötigt keine Diagramm-Laufzeit im Browser. Diese Reihenfolge ist wesentlich. Würde der Agent nur ein Diagrammbild liefern, bliebe unklar, welche Zahlen darin stecken. Würde er eine komplexe Chart-Konfiguration erzeugen, müsste das Review zugleich Daten, Darstellungscode und Sicherheitswirkung beurteilen. Eine Markdown-Tabelle trennt die fachliche Aussage von der Visualisierung – und bleibt zugleich die überprüfbare Quelle für Website und Diagramm. ## Praxisbeispiel: Quartalsreview Für ein Quartalsreview bietet sich folgende Architektur an: Ein separater Dienst fragt die Quellen zum Stichtag ab, normalisiert die Ergebnisse und liefert einen validierten Snapshot. In diesem vorgeschlagenen Ablauf darf erst nach erfolgreichen Quell-, Schema- und Zeitraumprüfungen eine Vorschau entstehen. Der Agent schreibt ausschließlich aus dem freigegebenen Snapshot das Markdown-Dokument. Der Bericht kann vier Kennzahlen zeigen: Umsatz, Marge, offene Risiken und SLA-Erfüllung. Darunter stehen eine Entscheidungskarte, ein Fortschrittsbalken für Quartalsziele sowie Diagramme zu Planabweichung und Verfügbarkeit. Am Ende folgt eine normale Markdown-Tabelle mit offenen Maßnahmen, Verantwortlichen und Terminen. Für die Besprechung ist die Website leichter lesbar als eine Rohdatei. Für den Nachweis bleibt die Markdown-Quelle erhalten. Im nächsten Quartal erzeugt der Agent einen neuen Report. Ein Vergleich der Revisionen zeigt, welche Kennzahlen, Aussagen und Maßnahmen sich verändert haben. ## Wo statische Reports passen Quartalszahlen sind nur ein Fall. Entscheidend sind der Stichtag und die spätere Nachvollziehbarkeit. Contentkit-Reports passen besonders zu folgenden Aufgaben: - SLA- und Service-Reviews mit Verfügbarkeit, Vorfällen und vereinbarten Maßnahmen - Inventur- und Kontenabgleiche mit gefundenen, unsicheren und verwaisten Positionen - Migrationsberichte mit verarbeiteten Datensätzen, Fehlerklassen und offenen Ausnahmen - Projekt- und Lieferberichte mit Durchsatz, Risiken, Entscheidungen und Zielerreichung - Compliance- oder Sicherheitsnachweise mit Prüfumfang, Befunden und verantwortlichen Maßnahmen - Incident-Reviews mit Zeitverlauf, Auswirkungen, Wiederherstellungsstand und Folgeschritten Diese Fälle haben einen gemeinsamen Kern: Der Bericht soll später noch dieselbe Aussage tragen. Ein Live-Dashboard kann die Vorbereitung unterstützen, ersetzt aber den freigegebenen Stand nicht. ## Reports für Anwender, nicht nur für Prüfer Leser öffnen den Servicebericht als responsive Website im Browser. Kennzahlwerte, Statuskarten, Fortschritt und Diagramme stehen direkt im Dokument. Die zugehörigen Tabellen bleiben als Belege erhalten, wenn Details geprüft werden müssen. Ein Projektteam kann den Bericht als gemeinsame Gesprächsgrundlage verwenden. Statt Screenshots aus mehreren Werkzeugen zusammenzutragen, verweist jede Entscheidung auf denselben Release. Offene Maßnahmen stehen als Text und Tabelle im Dokument, nicht als nicht exportierbare Tooltip-Information. Damit bleibt der Bericht auch ohne interaktive Diagrammkomponente prüfbar. ## Agenten können Berichte aus geprüften Snapshots erzeugen Für den hier beschriebenen Prozess gilt eine Designannahme: Berechnung und Validierung laufen außerhalb des Modells. Das Modell formuliert ausschließlich auf Basis eines geprüften Snapshots und ergänzt keine fehlenden Werte. ```ts type ServiceSnapshot = { period: string; availability: number; incidents: number; objectivesDone: number; objectivesTotal: number; openActions: Array<{ owner: string; finding: string; due: string }>; }; function validateSnapshot(snapshot: ServiceSnapshot) { if (snapshot.availability < 0 || snapshot.availability > 100) { throw new Error("Availability must be between 0 and 100"); } if (snapshot.objectivesDone > snapshot.objectivesTotal) { throw new Error("Completed objectives exceed total objectives"); } } ``` In der vorgeschlagenen Architektur erzeugt ein Dienst den geprüften Snapshot. Der Agent formuliert die Zusammenfassung, beschreibt darin markierte Abweichungen und setzt die Daten in die Contentkit-Direktiven ein. Ein zusätzliches Prüfschema sollte Tabellenüberschriften und Zeilenschlüssel stabilen Feldern des Snapshots zuordnen. Fehlt eine Zuordnung oder weicht ein Tabellenwert vom Snapshot ab, darf der Build nicht fortgesetzt werden. Nach erfolgreicher Prüfung kann ein Mensch die Vorschau im Cockpit begutachten. Automatisierbar sind das Lesen festgelegter Datenquellen, das Formatieren der Tabellen, das Gruppieren von Maßnahmen und das Formulieren einer Einleitung aus dem geprüften Snapshot. Fachliche Regeln und Freigaben bleiben ausdrücklich außerhalb des Modells. ## Unveränderliche Revision statt Screenshot Für den Vergleich ist entscheidend, dass die Veröffentlichung von einer unveränderlichen Revision ausgeht und die Markdown-Tabellen als Belege erhalten bleiben. Ein Dashboard-Screenshot allein belegt weder die zugrunde liegenden Quelldaten noch ihre Zuordnung zu einer unveränderlichen Revision. Beim Contentkit-Report lässt sich die veröffentlichte Darstellung dagegen auf den Markdown-Beleg des freigegebenen Stands beziehen. ## Ein Report braucht einen Lebenszyklus Die Erzeugung beginnt mit einem benannten Stichtag und einer Quellenliste. Danach folgen Berechnung, fachliche Prüfung, sprachliche Einordnung, Contentkit-Vorschau und Veröffentlichung. Wer diese Schritte nur als einen großen Prompt ausführt, kann später schwer feststellen, ob eine Zahl aus der Quelle, einer Berechnung oder dem Modell stammt. ```mermaid flowchart LR S["Stichtag und
Quellen fixieren"] --> B["Werte deterministisch
berechnen"] B --> A["Agent formuliert
Bericht"] A --> P["Zahlen und Aussagen
prüfen"] P --> V["Contentkit-Vorschau"] V --> R["Freigegebener Release"] R --> F["Archiv, Review
und Folgeprozesse"] ``` Zu jedem Report sollte ein Erzeugungsnachweis gehören: Zeitraum, Quellläufe, verwendete Regeln, Prüfresultat und Revisions-ID. Dieser Nachweis kann als Tabelle in derselben unveränderlichen Markdown-Revision liegen. Ein externes Audit-Protokoll muss über eine stabile ID referenziert werden. So kann ein späterer Leser den Stichtag und die Herkunft der Zahlen einordnen. Bei einer sachlichen Korrektur derselben Periode entsteht eine neue Revision mit dokumentiertem Grund. Ein eigenständiger Stichtag erhält einen eigenen Report. Redaktionell ist außerdem zwischen einem technischen Fehlrelease, bei dem freigegebene Inhalte nicht korrekt ausgeliefert wurden, und einer geänderten Fachgrundlage zu unterscheiden. Die geänderte Fachgrundlage benötigt eine neue Revision und einen neuen Erzeugungsnachweis. ## Serien machen Veränderungen sichtbar Wiederkehrende Reports sollten dieselbe Struktur und dieselben Feldnamen verwenden. Dann kann ein dafür geprüfter Prozess Perioden vergleichen, ohne jedes Mal ein neues Dokumentmodell zu benötigen. Kennzahlen bleiben an derselben Stelle, Maßnahmen verwenden dieselben Spalten und Diagramme dieselbe Einheit. Das bedeutet nicht, dass jede Ausgabe gleich aussehen muss. Ein neues Risiko verdient Raum, eine nicht mehr relevante Kennzahl darf entfallen. Der Unterschied wird jedoch ausdrücklich im Vergleich der Markdown-Revisionen sichtbar. Eine Serienübersicht kann auf alle Perioden verweisen und den aktuellen Bericht hervorheben. Für Anwender entsteht damit ein Verlauf aus freigegebenen Zuständen. Sie können den Juli-Bericht öffnen, ohne heutige Zahlen zu sehen, und anschließend den August-Bericht vergleichen. Ein Agent kann Veränderungen in diesem Prozess aus den Markdown-Tabellen zusammenfassen, statt Screenshots oder Pixelwerte auszuwerten. ## Eine einfache Auswahlhilfe Drei Fragen trennen die Fälle. Muss jemand innerhalb von Sekunden auf einen neuen Wert reagieren? Dann ist ein Live-Dashboard wahrscheinlich nötig. Muss der Stand später unverändert belegt werden? Dann braucht es einen Report. Müssen beide Anforderungen erfüllt werden? Dann liefert das Live-System die Beobachtung und ein regelmäßiger Contentkit-Report den freigegebenen Stichtag. Der Veröffentlichungsrhythmus folgt der fachlichen Entscheidung: täglich für einen Migrationslauf, wöchentlich für Lieferung, monatlich für SLA, quartalsweise für Geschäftszahlen oder einmalig für einen Incident. Derselbe technische Prozess kann diese Fälle abbilden, doch Zeitraum und Freigaberegel bleiben verschieden. Diese Auswahl schützt vor zwei Extremen: jedes Problem mit einer schwergewichtigen Live-Plattform zu lösen oder einen statischen Bericht dort einzusetzen, wo Menschen sofort reagieren müssen. Contentkit ersetzt weder ein Observability-System noch eine interaktive Analyseplattform. Seine Aufgabe ist die lesbare und prüfbare Veröffentlichung eines freigegebenen Stichtags. ## Fazit Contentkit ordnet einen prüfbaren Markdown-Report durch eine explizite Narrative und veröffentlicht ihn aus einer unveränderlichen Revision. Tabellen bleiben die Belege für Website und Diagramme; das Cockpit dient der Verwaltung und Vorschau vor dem Release. Die Architekturentscheidung folgt der benötigten Reaktion: Für einen freigegebenen Stichtag wird ein Report veröffentlicht. Wenn laufende Änderungen unmittelbare Reaktionen auslösen müssen, bleibt ein Live-System erforderlich. ## Weiterführende Quellen - [Markdown Reports statt Dashboard-Zwang](https://www.mikebild.dev/de/blog/markdown-reports-statt-dashboard/) - [Contentkit Reports und Dashboards](https://github.com/MikeBild/contentkit/blob/0a3e8ccef4bf6e73488a98444d91c8afe9f57a72/docs/REPORTS.md) - [Contentkit-Architektur](https://github.com/MikeBild/contentkit/blob/0a3e8ccef4bf6e73488a98444d91c8afe9f57a72/docs/ARCHITECTURE.md) - [Contentkit Cockpit UI/UX](https://github.com/MikeBild/contentkit/blob/0a3e8ccef4bf6e73488a98444d91c8afe9f57a72/apps/cockpit/UI-UX.md)