# Dashboards aus Markdown-Tabellen
URL: https://www.mikebild.dev/de/blog/dashboards-aus-markdown-tabellen/
Autor oder Agent liefert für ein Report-Diagramm eine Markdown-Tabelle, aber keine Koordinaten oder Renderer-Konfiguration. Die Tabelle enthält die Quelldaten, aus denen Contentkit die visuelle Darstellung ableitet. Typisierte Datenformen decken darüber hinaus Aussagen ab, die über gewöhnliche Zahlenreihen hinausgehen – etwa Veränderung, Unsicherheit oder Fluss.
*Teil 11 der Serie „Contentkit – Publishing für Maschinen“.*
Der enge Vertrag ist für Agenten und Reviews gleichermaßen nützlich. Ein Modell kann eine Tabelle aus geprüften Messwerten erzeugen. Ein Mensch kann sie Zeile für Zeile lesen. ContentKit führt diese Daten durch eine Kompositionsstrecke mit deterministischem Layout. Autoren müssen für diese Report-Diagramme keine separate Chart-Spezifikation pflegen.
## Von der Quelltabelle zur statischen Ausgabe
Der Weg von der Tabelle zum Diagramm folgt einer festen Kompositionsstrecke. Aus dem Markdown entsteht zunächst ein Semantic AST, der festhält, welche Datenform vorliegt und welche Bausteine ein Abschnitt enthält. Eine Narrative ordnet Leserfrage, Kernaussage und mögliche Handlung. Danach wählt ein deklaratives Pattern die Darstellungsform, das Layout berechnet die Geometrie und der Renderer erzeugt die statische Ausgabe. Autor oder Agent müssen dafür weder Koordinaten noch eine Renderer-Konfiguration liefern.
Diese Trennung macht die Verdichtung überprüfbar: Die vollständigen Werte liegen in der zugänglichen Quelltabelle, das Diagramm ergänzt diese Evidenz, ersetzt sie aber nicht. Markdown bleibt der redaktionelle Vertrag. Die visuelle Darstellung darf daraus keine neuen Zahlen oder Bedeutungen erfinden – sie ordnet und gewichtet, was in den Quelldaten steht.
Stand August 2026 beschreibt dieses Modell Contentkit 4.26.1. Kurzlebige Details einzelner Direktiven sind für die Architekturentscheidung nicht ausschlaggebend. Entscheidend bleibt die Trennung von Semantik, Narrative, deklarativem Pattern, Layout und Ausgabe.
## Report-Inhalte als Komposition abgrenzen
Report-Inhalte gehören in eine dafür vorgesehene Komposition. Diese Zuordnung trennt gewöhnlichen Fließtext von Dokumenten, in denen Kennzahlen, Status, Fortschritt, Tabellen und Diagramme gemeinsam einen Bericht bilden.
Der normale Markdown-Inhalt bleibt dabei Teil des Dokuments. Ein Report kann Erläuterungen, Überschriften, Listen und Quelltabellen mit visuellen Bausteinen verbinden. Die Darstellung ergänzt den Text, ohne einen zweiten Datenbestand neben dem Markdown einzuführen.
## Kontrollierte Bausteine statt freier Widgets
Contentkit bildet Report-Kompositionen aus einem begrenzten Satz semantischer Bausteine. Dazu gehören Kennzahlen, Status, Fortschritt, Tabellen und tabellengetriebene Diagramme. Jeder Baustein bezeichnet eine fachliche Funktion, nicht eine frei programmierbare Oberfläche.
Ein Lieferbericht kann beispielsweise mehrere Werte und einen Freigabestatus enthalten:
Das folgende Beispiel ist eine fachliche Quelldarstellung und keine zugesicherte Contentkit-Syntax.
```md
## Delivery Review July 2026
| Metric | Value |
|---|---:|
| Deployments | 42 |
| Failed deployments | 2 |
| Quarterly objectives completed | 8 |
| Quarterly objectives total | 10 |
Status: Approved
```
Die Quelltabelle hält die Werte unabhängig von ihrer späteren Darstellung fest. Die Erzeugungs- und Prüfstrecke sollte Kennzahlen, Fortschritt und Status auf dieselben geprüften Quelldaten zurückführen.
Ein vorgeschalteter externer Validator sollte erkennbare Vertragsverletzungen ablehnen, bevor sie an den Renderer gelangen; maßgeblich bleibt die Validierung der betriebenen Contentkit-Version. Ein frei programmierbares Widget könnte Widersprüche verbergen oder erst im Browser behandeln. Bei semantischen Bausteinen lässt sich die Eingabe dagegen vor der Ausgabe gegen ihren vorgesehenen Datenvertrag prüfen.
## Diagramme beginnen bei einer Markdown-Tabelle
Die Quelltabelle eines Diagramms kann so aussehen:
```md
| Environment | Successful | Failed |
|---|---:|---:|
| Development | 18 | 1 |
| Staging | 14 | 1 |
| Production | 10 | 0 |
```
Die erste Spalte bezeichnet hier die Umgebungen, die weiteren Spalten enthalten die zu vergleichenden Werte. Titel, Beschreibung und Einheit gehören zur Bedeutung des Diagramms, die Zahlen selbst bleiben in der Tabelle.
Das Diagramm darf diese Werte hervorheben oder räumlich ordnen. Es darf sie weder ersetzen noch still korrigieren. Wer eine Abweichung prüfen will, braucht deshalb keinen Zugriff auf interne Zeichenbefehle, sondern liest die Zeile der Quelltabelle.
## Gewöhnliche Zahlenreihen und typisierte Datenformen
Gewöhnliche Zahlenreihen eignen sich für Vergleiche und zeitliche Verläufe. Welche Diagrammform fachlich passt, hängt von der Aussage ab. Kategorien nach Umgebung benötigen eine andere Darstellung als Messwerte über mehrere Wochen.
```md
| Month | Product | Platform |
|---|---:|---:|
| May | 18 | 11 |
| June | 22 | 14 |
| July | 25 | 16 |
```
Für Aussagen jenseits solcher Reihen verwendet Contentkit typisierte Datenmuster. Das Datenmuster beschreibt die semantische Form. Das Pattern ordnet dieser Form und der Narrative eine geeignete Darstellung zu; das Layout berechnet deren Geometrie.
Ein Vorher-Nachher-Vergleich kann etwa auf dieser Tabelle beruhen:
```md
| Pipeline | Before | After |
|---|---:|---:|
| Test | 18.4 | 9.2 |
| Package | 12.1 | 10.8 |
| Deploy | 7.6 | 6.9 |
```
Konzeptionell umfasst die begleitende Narrative die Leserfrage, die belegte Erkenntnis, eine mögliche Handlung und die Einschränkung der Daten. Der folgende Block illustriert diese fachlichen Bestandteile, nicht die konkrete Contentkit-Syntax:
```md
Question: Which pipeline improved most?
Insight: The test pipeline shows the largest reduction.
Action: Review whether the same cache boundary applies to packaging.
Limitation: The comparison covers one week per state.
```
Die Tabelle trägt die Messwerte. Die Narrative trägt die fachliche Einordnung. Diese beiden Ebenen bleiben getrennt prüfbar.
## Begrenzung hält die Komposition prüfbar
Ein Report-Vertrag muss die zulässigen Direktiven und Datenformen begrenzen. Sonst wird aus einem deklarativen Bericht schrittweise eine allgemeine Programmierschnittstelle für Visualisierungen.
Die konkrete Grenze gehört zur jeweiligen betriebenen Version. Für die Architektur zählt ihre Wirkung: Ein Generator kann Eingaben gegen einen endlichen Vertrag prüfen. Das Layout verarbeitet bekannte semantische Formen. Die statische Ausgabe bleibt aus den Quelldaten und der redaktionell festgehaltenen Narrative ableitbar.
```mermaid
flowchart LR
D["Geprüfte Daten"] --> A["Agent erzeugt
Markdown-Tabelle"]
A --> V["Vertrag prüfen
Semantik und Datenform"]
V --> S["Deterministische
Komposition"]
S --> R["Statische Ausgabe
Diagramm plus Tabelle"]
V -. Fehler .-> A
```
Ein Bericht sollte nur die Verdichtung enthalten, auf die sich Aussage und Entscheidung beziehen. Rohmesswerte können im Quellsystem oder in einem separaten Datenartefakt bleiben. Die Tabelle im Report enthält dagegen genau die Quelldaten, die den sichtbaren Aussagen zugrunde liegen.
## Praxisbeispiel: wöchentlicher Lieferbericht
Ein Entwicklungsteam möchte jede Woche vier Fragen beantworten: Was wurde ausgeliefert? Wie stabil war die Lieferung? Welche Ziele sind erreicht? Welche Risiken benötigen eine Entscheidung?
In einem möglichen Aufbau sammelt eine Pipeline Deployments, fehlgeschlagene Builds, Durchlaufzeiten und bestätigte Vorfälle. Deterministische Funktionen berechnen daraus Wochenwerte. Ein Agent formuliert die Zusammenfassung und erzeugt Markdown mit Kennzahlen, Status, Fortschritt, Diagramm-Quelldaten und einer Tabelle für Maßnahmen, Verantwortliche und Termine.
Die Prüfstrecke kann die Zahlen zunächst gegen das erzeugende Datenobjekt vergleichen. Ein weiterer Lauf kann die Vorschau erzeugen und kontrollieren, ob die veröffentlichten Tabellenzellen den erwarteten Werten entsprechen. Erst danach wird der Bericht freigegeben.
Jede hervorgehobene Kennzahl muss auf lesbare Quelldaten oder eine nachvollziehbare Berechnung zurückführen.
## Agenten sollen Daten nicht erfinden
Ein LLM kann fehlende Werte elegant erklären und dadurch gefährlich überzeugend wirken. Der Report-Vertrag darf deshalb nicht der einzige Prüfschritt sein. Eine strukturell gültige Tabelle belegt noch nicht, dass `25` tatsächlich die Zahl abgeschlossener Arbeitspakete war.
Die Erzeugungsstrecke sollte Zahlen aus einer überprüfbaren Quelle übernehmen und ihre Herkunft festhalten. Ein möglicher Zwischenvertrag sieht so aus:
```ts
type DeliveryWeek = {
week: string;
successfulDeployments: number;
failedDeployments: number;
leadTimeHours: number;
sourceRunId: string;
};
function renderDeliveryRow(row: DeliveryWeek) {
return `| ${row.week} | ${row.successfulDeployments} | ${row.failedDeployments} | ${row.leadTimeHours} |`;
}
```
Der Agent darf erläutern, warum sich Werte verändert haben, wenn dafür Belege vorliegen. Fehlt ein Beleg, sollte er die Abweichung als offene Frage markieren. Das ist nützlicher als eine plausible Ursache.
## Darstellung verändert keine Quelldaten
Farben, Abstände und Typografie gehören zur Darstellung. Die Zahlen und ihre fachliche Bedeutung gehören in den Markdown-Vertrag. Eine Änderung des visuellen Erscheinungsbilds darf deshalb weder Tabellenwerte noch Einheiten oder Aussagen verändern.
Diese Trennung ist für wiederkehrende Berichte entscheidend. Ein späteres Layout kann denselben Datenbestand anders anordnen, ohne Werte oder Aussagen zu ändern. Der überprüfbare Bezug zwischen Diagramm und Quelltabelle bleibt erhalten.
## Maschinenlesbare Nutzung bleibt möglich
Weil Markdown der redaktionelle Vertrag bleibt, kann eine nachgelagerte Integration denselben Inhalt verarbeiten, sofern sie autorisierten Zugriff auf das veröffentlichte Dokument oder dessen Quelldaten besitzt. Dafür muss sie Zahlen nicht aus gezeichneten Formen rekonstruieren.
Eine mögliche Integration liest die Tabellen und den erklärenden Text und erzeugt daraus eine Quartalszusammenfassung. Ob dafür eine Website, ein Export oder eine autorisierte Schnittstelle verwendet wird, ist eine Frage der jeweiligen Veröffentlichungsarchitektur.
## Der Preview-Test prüft mehr als Syntax
Eine formal gültige Tabelle kann fachlich unverständlich sein. Zu viele Reihen, abgeschnittene Kategorien oder eine unpassende Diagrammform können den Datenvertrag erfüllen und trotzdem schlechte Kommunikation erzeugen. Deshalb gehört zur Vorschau ein Darstellungscheck mit realistischen Daten.
Ein Prüfagent kann strukturelle Regeln bewerten: Sind erwartete Spalten vorhanden? Bleiben Einheiten konsistent? Entsprechen hervorgehobene Kennzahlen den Werten der Quelltabelle? Andere Fragen benötigen eine fachliche oder visuelle Entscheidung.
Ein Liniendiagramm für ungeordnete Kategorien wäre beispielsweise irreführend, weil die Verbindung der Punkte eine Reihenfolge oder Kontinuität suggeriert. Umgebungen wie Development, Staging und Production sind zwar benennbar, besitzen aber nicht automatisch die zeitliche Kontinuität einer Messreihe.
Ein mögliches externes Prüfergebnis:
```yaml
chart_review:
title: Deployments by environment
source_rows: 3
numeric_cells: 6
missing_values: 0
unit_consistent: true
metric_total_matches: true
visual_review: required
```
Für diesen Bericht umfasst die Prüfliste die vorgesehene Darstellung und einen schmalen Bildschirm. Falls eine Druckausgabe zum Lieferumfang gehört, wird auch diese konkrete Ausgabe geprüft. Die Eignung der Daten und der gewählten Diagrammform bleibt Teil des Reviews.
## Verdichtung muss fachlich benannt sein
Wenn Rohdaten vor der Veröffentlichung aggregiert werden, ist das keine reine Formatierung. „Durchschnitt pro Woche“ beantwortet eine andere Frage als „Maximum pro Stunde“. Ein Agent darf die Methode nicht still wählen. Der Report sollte die Verdichtung in Prosa oder Metadaten nennen.
```md
## Data basis
The line shows the weekly median lead time for completed changes. Aborted runs
and drafts are excluded. The source is the approved export
`delivery-2026-07-27`.
```
Für Ausnahmen kann eine normale Tabelle besser sein als ein Diagramm. Fünf kritische Vorfälle mit Ursache und Maßnahme lassen sich als Zeilen genauer lesen. Das Dashboard soll Aufmerksamkeit lenken, nicht jede Information in eine grafische Form pressen.
## Lokalisierung der Zahlen bewusst behandeln
Quelldaten und lokalisierte Darstellung erfüllen unterschiedliche Aufgaben. Die Tabelle sollte einen eindeutigen Datenwert enthalten. Der sichtbare Text kann denselben Wert in der für Leser üblichen Schreibweise wiedergeben.
`99.93` kann beispielsweise der Datenwert sein, während eine deutsche Kennzahlenkarte `99,93 %` zeigt. Die Trennung von Datenwert und lokalisierter Darstellung verhindert, dass eine sprachabhängige Schreibweise unterschiedlich interpretiert wird.
## Fehler als Vertragsbeispiele nutzen
Ein externer Validator kann typische Fehler bereits vor der Übergabe an Contentkit erkennen. Dazu gehören nicht numerische Werte in Zahlenspalten, fehlende Pflichtspalten eines Datenmusters oder eine Kennzahl, die nicht zur Quelltabelle passt.
```ts
const invalidReportCases = [
{ name: "formatted number", cell: "99.9%", expected: "reject" },
{ name: "infinite number", cell: "Infinity", expected: "reject" },
{ name: "missing required column", expected: "reject" }
];
```
Diese Liste ist ein Beispiel für eine vorgeschaltete Prüfung, keine Contentkit-API. Der Generator sollte das Prüfergebnis zusammen mit der verwendeten Contentkit-Version festhalten. So bleibt nachvollziehbar, nach welchen Regeln ein Entwurf geprüft wurde.
Vor der Veröffentlichung zählt der Vertrag der tatsächlich betriebenen Version. Für wiederkehrende Berichte lohnt sich zusätzlich eine kleine Fixture mit typischen und ungültigen Tabellen in der CI. Damit fallen Änderungen an Spalten, fehlenden Werten oder Einheiten auf, bevor ein vollständiger Berichtsbestand erzeugt wird.
## Fazit
Prüfbare Tabellen und sichtbare Quelldaten rechtfertigen die Entscheidung gegen frei programmierbare Widgets. Der begrenzte Vertrag bindet jede statische Ausgabe an die semantisch ausgewerteten Quelldaten, ohne eine zweite Datenquelle in der Visualisierung zu verstecken.
Wer reproduzierbare Stichtagsberichte benötigt, sollte diese Begrenzung bewusst wählen. Sie macht generiertes Markdown zu einem prüfbaren Eingang für den Release-Build und hält jede Verdichtung an die veröffentlichten Quelldaten gebunden.
## Weiterführende Quellen
- [Contentkit Reports und Dashboards](https://github.com/MikeBild/contentkit/blob/94a738ef791ffd5fec12e71eaf6ef64fa556c090/docs/REPORTS.md)
- [Contentkit Information Blocks](https://github.com/MikeBild/contentkit/blob/94a738ef791ffd5fec12e71eaf6ef64fa556c090/docs/INFORMATION_BLOCKS.md)
- [Contentkit Visual Compositions](https://github.com/MikeBild/contentkit/blob/94a738ef791ffd5fec12e71eaf6ef64fa556c090/docs/VISUAL_COMPOSITIONS.md)
- [Contentkit README](https://github.com/MikeBild/contentkit/blob/94a738ef791ffd5fec12e71eaf6ef64fa556c090/README.md)