Plan: arc42-Dokumentation für Jekyll kompilieren

Ausgangslage

/documentation/architecture/
├── 01-einfuehrung-ziele.adoc
├── 02-randbedingungen.adoc
├── 03-kontextabgrenzung.adoc
├── 04-loesungsstrategie.adoc
├── 05-bausteinsicht.adoc
├── 08-querschnittliche-konzepte.adoc
├── 08-4-cloud-deployment.adoc
├── 08-CAP-device-binding.adoc
├── 08-fly-io-concept-proposal-gemini.adoc
├── 09-architekturentscheidungen.adoc
├── 09-user-management-admin-concept.adoc
└── images/puml/*.puml (9 Diagramme)

Aktuell: make docs (in /documentation/) erzeugt HTML in build/ Ziel: Integration in Jekyll unter /architecture/arc42/

Option A: AsciiDoc → HTML-Fragment → Jekyll (Empfohlen)

Ablauf

AsciiDoc (Source)     →  HTML-Fragment      →  Jekyll Page
01-einfuehrung.adoc   →  01-einfuehrung.html →  /architecture/arc42/01/

Umsetzung

Neues Script: docs/scripts/compile-arc42.sh
- Verwendet asciidoctor im Docker-Container
- Erzeugt HTML-Fragmente (ohne <html>, <head>, etc.)
- Fügt Jekyll Front Matter hinzu
- Output: docs/_arc42/*.html

Docker-Service: compile-arc42 in docs/docker-compose.yml

compile-arc42:
  image: asciidoctor/docker-asciidoctor
  volumes:
    - ../documentation/architecture:/source:ro
    - ./_arc42:/output
    - ./scripts:/scripts:ro
  command: ["sh", "/scripts/compile-arc42.sh"]

Jekyll-Collection: _arc42 in _config.yml

collections:
  arc42:
    output: true
    permalink: /architecture/arc42/:name/

Makefile: website-compile erweitern

website-compile:
  @mkdir -p docs/_adrs docs/_arc42
  @cd docs && docker compose run --rm compile-adrs
  @cd docs && docker compose run --rm compile-arc42

Bilder: PlantUML → SVG
- Option 1: Vorher manuell generieren, in Git committen
- Option 2: Bei compile-arc42 mit generieren (PlantUML-Server)

Vorteile

✅ Bewährtes Muster (wie ADRs)
✅ Source of Truth bleibt /documentation/
✅ Volle AsciiDoc-Features (Tabellen, Admonitions, etc.)
✅ Funktioniert mit GitHub Pages

Nachteile

⚠️ Zusätzlicher Docker-Container (asciidoctor)
⚠️ PlantUML-Bilder brauchen Extra-Handling

Option B: jekyll-asciidoc Plugin

Umsetzung

AsciiDoc-Dateien direkt in docs/_arc42/ kopieren
Jekyll-Plugin jekyll-asciidoc parst sie

Vorteile

✅ Kein Konvertierungsschritt

Nachteile

❌ Funktioniert NICHT mit GitHub Pages (unsupported plugin)
❌ Lokaler Build weicht von Production ab
❌ CI/CD muss Jekyll selbst bauen (kein github-pages gem)

→ Nicht empfohlen

Option C: AsciiDoc → Markdown (Pandoc)

Umsetzung

pandoc oder kramdoc für Konvertierung
Output: Markdown-Dateien für Jekyll

Vorteile

✅ Native Jekyll-Unterstützung

Nachteile

❌ Verlust von AsciiDoc-Features (komplexe Tabellen, Admonitions)
❌ Manuelle Nacharbeit nötig
❌ Bilder/Includes funktionieren anders

→ Nicht empfohlen

Empfehlung: Option A

Dateien zu erstellen/ändern

Datei	Aktion
`docs/scripts/compile-arc42.sh`	Neu
`docs/docker-compose.yml`	Service hinzufügen
`docs/_config.yml`	Collection hinzufügen
`Makefile`	`website-compile` erweitern
`docs/_pages/architecture/arc42.md`	Index-Seite mit Kapitel-Links
`.gitignore`	`_arc42` hinzufügen

Offene Fragen

Kapitel-Struktur:
- Alle Kapitel einzeln?
- Oder ein großes Dokument?
PlantUML-Diagramme:
- Vorher generieren und committen?
- Oder bei jedem Build generieren?
Navigation:
- Inhaltsverzeichnis auf arc42-Seite?
- Vor-/Zurück-Navigation zwischen Kapiteln?
Geschützter Bereich:
- arc42 auch hinter Passwort (layout: protected)?

Nächste Schritte (nach Freigabe)

compile-arc42.sh Script erstellen
Docker-Service hinzufügen
Jekyll-Collection konfigurieren
Makefile erweitern
arc42-Index-Seite erstellen
Testen mit make website-dev