Dokumente, die man
nachbauen kann

Typst ist ein Satzsystem: Man schreibt Text mit wenigen Auszeichnungen in eine Datei, Typst setzt daraus ein PDF.

Gegenüber einer Textverarbeitung liegt alles in einer lesbaren Textdatei. Sie lässt sich versionieren, vergleichen und automatisch übersetzen – dieselbe Quelle ergibt dasselbe PDF. Gegenüber LaTeX ist die Syntax knapper, Fehlermeldungen nennen Datei, Zeile und Spalte, und Vorlagen sind Funktionen in einer richtigen Programmiersprache.

Überschriften beginnen mit =, Fettdruck steht zwischen Sternchen (*fett*), Funktionen beginnen mit #: #table(…), #image(…), #bibliography(…). Formeln stehen zwischen Dollarzeichen. Daten kommen per json(…), csv(…) oder yaml(…) direkt in das Dokument.

Dieser Leitfaden nutzt typstgen: ein kleines Werkzeug, das .typ-Dateien mit eingebetteter Typst-Engine zu PDF übersetzt – als Kommandozeile, als Rust-Bibliothek, als WebAssembly und als MCP-Server für KI-Agenten. Ein installiertes typst braucht es nicht.

Ein Dokument entsteht aus Daten und einer Vorlage. Was danach passiert, entscheidet, ob man ihm in acht Jahren noch trauen kann.

check meldet Fehler mit Datei, Zeile und Spalte, preview zeigt eine Seite als Bild, compile schreibt das PDF – auf Wunsch als PDF/A und bei Rechnungen mit eingebettetem ZUGFeRD-XML.

Ein Manifest hält fest, woraus jedes PDF entstanden ist. verify baut es später neu und vergleicht Byte für Byte. Die drei Prüfschritte stehen auch einem KI-Agenten über MCP zur Verfügung.

Für die meisten Dokumente reicht typstgen mit einer Vorlage. Wer Berichte aus Programmcode erzeugt, nimmt eine Bibliothek.

typstgen übersetzt beliebige .typ-Dateien. Vorlagen findet es über template_paths in typstgen.toml, Typst-Pakete wie @preview/… lädt es aus denselben Ordnern wie die Typst-CLI – oder gar nicht, wenn man es so einstellt.

business-templates bringt 19 Geschäftsdokumente als Typst-Paket mit: Rechnung, Angebot, Gutschrift, Mahnung, Lieferschein, Auftragsbestätigung, Brief, Zugangsdaten, Konzept, Vertrag, Dokumentation, Projektvorschlag, Protokoll, SLA, Spezifikation, Aufgabenliste, Stundenzettel und Handout. Buchhaltungsdokumente nehmen JSON-Daten, die übrigen benannte Parameter und den Text als Inhalt.

RenderReport ist eine Rust-Bibliothek für datengetriebene Berichte aus Komponenten (Kennzahlen, Befunde, Tabellen, Diagramme), mit Typst als eingebetteter Engine; jedes PDF entsteht als PDF/UA-1.

Was sich ändert, sind die Daten. Was gleich bleibt, ist die Vorlage. Das PDF ist nur das Ergebnis.

Bewährt hat sich ein Ordner je Dokumentart und Jahr, der Dateiname ist die Dokumentnummer: invoices/2026/RE-2026-001.json enthält die Daten, RE-2026-001.typ daneben ist ein dünner Wrapper, der Vorlage und Daten zusammenführt. Stammdaten wie company.json liegen einmal zentral.

Daten, Wrapper und Manifest sind kleine Textdateien und gehören in die Versionsverwaltung; die Historie zeigt, wer was wann geändert hat. Die PDFs gehören ins Archiv, nicht ins Git – das Manifest verbindet beide.

Wer eine Wissensbasis für KI-Systeme pflegt, hält dort eine kompakte Zusammenfassung jedes Vorgangs und verweist mit document_id und typst_source auf die Quelle. Das System liest den Eintrag, der Kunde bekommt das PDF; PDFs gehören nicht in den Suchindex.

Seit 2025 müssen Unternehmen E-Rechnungen empfangen können; ausstellen müssen sie sie spätestens ab 2028.

Eine ZUGFeRD-Rechnung ist ein PDF/A-3, das dieselben Angaben zusätzlich als XML trägt (UN/CEFACT CII, Profil EN 16931). Umsatzsteuerlich ist das XML der führende Teil.

typstgen erzeugt das XML aus denselben JSON-Daten, aus denen die Rechnungsvorlage das PDF setzt. Vorher rechnet es Positionen, Steuer je Kategorie und Summen nach; weichen die Zahlen im JSON ab, bricht der Build ab – sonst zeigte das PDF etwas anderes als das XML. Abgedeckt sind Normal- und ermäßigter Satz, 0 %, steuerbefreit mit Begründung und Reverse Charge.

PDF/A sorgt dafür, dass eine Datei lesbar bleibt. Dass sie unverändert ist, muss man zusätzlich belegen.

typstgen compile --manifest archive.json schreibt zu jedem PDF auf, aus welcher Quelle, mit welchen Optionen und aus welchen Dateien es entstand – mit SHA-256 von PDF, Vorlagen, Daten, Bildern, Paketdateien und Schriften.

typstgen verify prüft später drei Dinge: Das abgelegte PDF ist unverändert, ein Neubau liest dieselben Dateien, und er ergibt dieselben Bytes. Damit das gelingt, braucht jedes Dokument einen festen Zeitstempel und festgelegte Schriften und Pakete.

Lokal ist die Prüfung verbindlich, in der CI ist sie der Nachweis beim Release.

Vor jedem Push läuft typstgen verify – als Skript oder als pre-push-Hook. In der CI fehlen die PDFs, weil sie im Archiv liegen; dort prüft verify --rebuild-only nur, ob jede Quelle die protokollierten Bytes ergibt.

Damit ein Neubau auf einem anderen Rechner gleich ausfällt, gehören Schriften und Pakete ins Repository: use_system_fonts = false, font_paths = ["fonts"], package_path mit download_packages = false. Eine Vorlage, die eine Systemschrift wie Helvetica anfordert, sieht unter Linux sonst anders aus.

Ein KI-Agent schreibt Typst schnell – und macht Fehler. Über MCP kann er sie selbst finden und beheben.

typstgen mcp ist ein Model-Context-Protocol-Server auf stdin/stdout. Er stellt vier Werkzeuge bereit: check (Fehler mit Zeile und Spalte, schreibt nichts), preview (eine Seite als Bild), compile (PDF, auf Wunsch als PDF/A oder ZUGFeRD) und list_templates. Alle Pfade sind auf das Arbeitsverzeichnis beschränkt.

Bewährt hat sich eine Arbeitsteilung: Der Agent schreibt Daten (JSON) und Text, die Vorlage sorgt für das Layout, ein Mensch prüft das Ergebnis vor dem Versand. Für E-Rechnungen kommen die Daten aus der Buchhaltung, nicht aus dem Sprachmodell.