䷢ JSON vs. YAML als Template-Datenquelle & Markdown als Ausgabe

Für Dokumenten-Generatoren ist in der Praxis oft sinnvoll, eine strukturierte Datenquelle (YAML oder JSON) als Single Source of Truth zu nutzen und daraus per Template-Engine sowohl Markdown als auch HTML/PDF-Outputs zu generieren. YAML ist dabei meist lesbarer für Menschen, JSON ist maschinenfreundlicher und API-kompatibel.

Status: published Erstellt: 5. November 2025 Kategorie: Blog Fehlersuche Datenschutz Tags: YAML Markdown

🔹 Vorteile und Nachteile

JSON -

Vorteile:
Nachteile:

YAML – human-lesbare Datenquelle mit stärkeren Feature

Vorteile:Lesbar, kommentierbar, ideal für Konfigs und Template-DatenUnterstützt Anchors/Referenzen, Multidokumente, einfache StrukturierungWeit verbreitet in DevOps-/CI-Umgebungen (kann leicht von Menschen gepflegt werden)
Nachteile:Indentation-Sensitivität – Fehlerquellen durch EinrückungenWeniger robust in sehr großen Dateien gegenüber JSON in einigen Parsing-SzenarienBei sicherheitskritischen Parsing-Szenarien: nutze Safe-Loader/Restriktiv-Parser

🔹 Markdown als Ausgabe vs. HTML/PDF

Markdown (MD) als Output

Vorteile
Nachteile:

HTML oder PDF via Weiterverarbeitung

Vorteile:Westeutliches Layout, einfache Veröffentlichung im WebPDF für Abschlussberichte, offizielle Dokumente
Nachteile:Zusätzlicher Rendering-Schritt nötig (z. B. Pandoc, Template-Engines)

🎯 Praktische Nutzung für einen Dokumenten-Generator

Quellformat wählen:
Template-Engine auswählen:
Outputs definieren:
Workflow:

🧰 Schnelles Beispiel

Beispiel-Daten (YAML):

document:
  title: "Canary-Rollout Checkliste"
  version: "1.0"
  sections:
    - name: "Vorbereitung"
      items:
        - text: "Definition der Erfolgskriterien"
        - text: "Rollen & Freigabeprozesse definieren"
    - name: "Technische Umsetzung"
      items:
        - text: "Traffic-Splitting konfigurieren"
        - text: "Automatisches Rollback-Setup testen"

Beispiel-Template (Handlebars-ähnlich) für MD-Ausgabe:

# {{document.title}}

{{#document.sections}}
## {{name}}
{{#items}}
- {{text}}
{{/items}}
{{/document.sections}}

Render-Schritte (hoch-level):

YAML laden, Template mit Daten füllen, Ausgabe speichern (MD/HTML).

Tools: js-yaml/PyYAML zum Laden, Handlebars/Jinja2 zum Rendern, Pandoc zur Umwandlung in HTML/PDF.

💡 Praktische Tipps

Nutze eine klare Single-Source-of-Truth-Datei (YAML oder JSON) und generiere daraus MD/HTML.
Wähle YAML für manuelles Editing;
JSON, wenn Daten direkt aus APIs kommen oder starke Validierung erforderlich ist.
Vermeide Duplizierung von Informationen zwischen YAML/JSON und MD.
Nutze Templates, um eine einzige Quelle zu rendern.
Schütze sensible Daten (Secrets) beim Rendering und maskiere sie in Outputs.

Weitere Ressourcen: YAML – yaml.org, JSON – json.org, Handlebars, Pandoc