guides/templates/Format/MiniGuide.md

MINI-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)

FORMAT
- A4 Hochformat, 3-5 Seiten
- @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
- Footer: Seitenzahl Mitte, Guide-Titel rechts

ABDECKUNG (niedrigste Guide-Stufe)
- ALLE Kern-Bausteine des Themas — was man braucht, um anzufangen.
  Welche das sind, hängt vom Thema ab.
- Das Themeninventar wird vorab von einem Recherche-Agenten erstellt und
  mitgeliefert. Es ist verbindlich: jeder Punkt bekommt eine Sektion.
- Sektionen ohne Kapitel-Struktur; Code-Beispiele sehr kurz (2-7 Zeilen)
- ~15-25 Min Lesezeit, 3-5 Seiten — diese Obergrenze gilt immer

ZIELGRUPPE — KOMPAKTER ANFÄNGER-EINSTIEG
- Echte Anfänger ohne Programmier-Vorwissen im Thema
- Setzt nur allgemeines Verständnis voraus ("was ist Programmieren")
- Begriffe werden bei erstem Auftreten erklärt
- KEIN Sprach-Charakter-Überblick für erfahrene Entwickler
- KEINE fortgeschrittenen Features (auch wenn cool und kurz)

INHALTLICHE PRINZIPIEN
- Nur absolute Basics zeigen
- Themen, die jemand nach 15 Min selbst nachmachen kann
- Keine Tooling-Komplexität (Paketmanager, Build-Systeme, Compiler)
- Keine Sprach-Spezialitäten (Type-Systeme, Decorators, Generics)
- Keine OOP, wenn möglich (oder nur trivialste Form)
- Erklär-Tiefe vor Feature-Breite
- Lieber 5 Konzepte gründlich als 15 oberflächlich

TYPISCHE 5-SEKTIONEN-STRUKTUR
1. Sprache starten — Installation, erste Datei, erstes Programm
2. Variablen — Konzept + 2-3 Basis-Typen
3. Kontrollfluss — if/else mit einfachem Beispiel
4. Listen + Iteration — Array + Schleife
5. Funktionen — Deklaration + Aufruf + Rückgabe

(Diese Reihenfolge baut aufeinander auf und endet mit etwas Sinnvollem.)

STRUKTUR
1. Kompakter Head: Logo links (16mm), Titel + Subtitle mittig, Badge + Zeit rechts
2. Gap-Opener: Frage zum Einstieg, kursiv eingerahmt, niedrigschwellig
3. 4-6 H2-Sektionen mit Erklärtext + Code-Beispiel + ggf. Callout

ELEMENTE
- Fließtext: justify mit Silbentrennung
- Codeblöcke: dunkler Hintergrund, syntax highlighting, sehr kurz (2-7 Zeilen)
- Inline-Code: heller Hintergrund, Hauptfarbe
- Tabellen: nur wenn wirklich nötig (Vergleichs-Operatoren o.ä.)
- Callouts in 3 Varianten: tip (grün), warn (rot), note (Hauptfarbe)

TYPOGRAFIE
- Body: 10.5pt Serif (Charter), line-height 1.55
- Head h1: 20pt Sans-Serif bold
- H2 Sektion: 13pt Sans-Serif bold
- Code: 8.5pt Monospace, line-height 1.5
- Inline-Code: 9pt Monospace
- Callout-Labels: 8pt uppercase, letter-spacing 1pt

FARBEN (max 3 + Neutrals)
- Hauptfarbe: kräftig, an offizielle Farbe des Themas anlehnen
- Hauptfarbe-Dunkel: dunklere Variante für Akzente
- Hintergrund-Soft: helle Variante der Hauptfarbe
- Code-Hintergrund: #1e2a3a
- Text: #1a1a1a / muted #5a6470 / Linie #d8dde3
- Callout-Farben: grün/rot/Hauptfarbe

GAP-OPENER (PFLICHT)
- Kursiv, eingerahmt mit Hauptfarbe-Border
- Niedrigschwellige Frage, die der Guide beantwortet
- Begeistert mit relevanter Statistik oder Praxis-Bezug
- KEINE Fachbegriffe, die noch nicht erklärt sind
- Beispiele:
  - "PHP läuft hinter rund drei Viertel aller Webseiten..."
  - "JavaScript ist die Sprache des Webs – aber wie schreibt man das eigentliche Code..."
  - "Python ist die beliebteste Anfänger-Sprache..."

ERKLÄR-TIEFE PRO KONZEPT
- Konzept benennen (z.B. "Variable")
- In einem Satz erklären, was es ist
- Code-Beispiel mit Kommentaren
- Sprach-Eigenheiten erwähnen (z.B. "in PHP beginnen Variablen mit $")
- KEIN Verweis auf andere Konzepte, die noch kommen

CALLOUT-NUTZUNG
- tip (grün): Übungs-Anregung am Ende, ermutigend
- warn (rot): Anfänger-Stolperfallen ("= vs ==", "vergessenes Semikolon")
- note (Hauptfarbe): Hintergrund-Info, Erklärung einer Sprach-Eigenheit

CALLOUT-CSS WICHTIG
- .callout-body > b:first-child mit display:block für Label
- NICHT .callout-body b global mit display:block (zerstört Inline-Bold)

GAP-CSS WICHTIG
- .gap > b:first-child mit display:block für "FRAGE ZUM EINSTIEG"-Label
- NICHT .gap b global mit display:block (zerstört Inline-Bold im Frage-Text)

THEMENSPEZIFISCHE ANPASSUNGEN (vor Generierung wählen)
- Hauptfarbe: offizielle Farbe des Themas
- Logo-Buchstabe(n) oder Kürzel
- Begrüßungs-Statistik im Gap-Opener
- 4-6 Anfänger-Themen wählen (siehe Standard-Struktur)

PFLICHT-ELEMENTE
- 1 Gap-Opener am Anfang
- 5-7 Code-Beispiele (kurz, 2-7 Zeilen, anfänger-tauglich)
- Mindestens 1 Callout (oft: warn für Stolperfalle, tip für Übung am Ende)
- Inline-Codes für Fachbegriffe

VERMEIDEN
- TOC oder Cover (überdimensioniert für 15 Min)
- Einleitungs-Floskeln ("In diesem Mini-Guide lernen wir...")
- Vollständigkeitsanspruch (gehört in größeren Guide)
- Referenz-Tabellen ohne Erklärtext (gehört in Cheatsheet)
- Recall oder Next-Step am Ende (Mini-Guide endet mit Inhalt)
- Themen, die fortgeschritten sind (auch wenn cool):
  - Type-Systems, Type-Hints, Generics
  - OOP-Features (außer trivialster Form)
  - Tooling (Paketmanager, Build, Linting)
  - Sprach-Spezialitäten (PHP: strict_types, readonly, Composer, PSR-4)
- page-break mitten in Codeblock oder Callout (page-break-inside: avoid)
- Mehr als 3 Schriftgrößen pro Sektion
- Floats oder absolute positioning (bricht in WeasyPrint)
- Fachbegriffe ohne Erklärung
- Verweise auf andere Konzepte, die noch kommen
- Edge Cases und "aber"-Sätze

GENERIERUNG MIT FEEDBACK-LOOP (max 3 Iterationen)
1. HTML schreiben
2. weasyprint file.html file.pdf
3. PDF zu PNGs: alle Seiten konvertieren
4. Alle Seiten ansehen
5. Prüfen:
   - Head sauber (Logo überlappt nicht mit Titel)?
   - Code-Blöcke nicht über Seitenumbruch zerrissen?
   - Callouts vollständig sichtbar?
   - Inline-Bolds in Callouts/Gap korrekt (nicht als Blöcke)?
   - Footer mit Seitenzahl korrekt?
   - Würde ein echter Anfänger das verstehen?
   - Wurden alle Fachbegriffe beim ersten Auftreten erklärt?
6. Bei Problemen: fixen, ab Schritt 2 wiederholen
7. Nach max 3 Iterationen ausgeben

INSTALLATION
- pip install weasyprint pdf2image
- apt install poppler-utils

DARKMODE (PFLICHT)

• Alle Farben ausschließlich über :root-Variablen definieren (--ink, --muted, --line, --bg-soft, Akzent-Variablen).
• Zusätzlich einen Dunkelmodus-Block ausliefern: @media screen { html[data-theme="dark"] { ...dunkle Variablenwerte... } html[data-theme="dark"] body { background: #15171c; } }
• Die App aktiviert ihn über data-theme="dark" auf <html>. KEIN prefers-color-scheme verwenden.
• Dunkle Werte: Hintergründe dunkel (#15171c / #23262e), Text hell (#e6e8ee), Linien gedämpft (#2c3038). Akzentfarben so anheben, dass Überschriften und Links auf dunklem Grund lesbar bleiben (Kontrast prüfen). Elemente mit hellem Text auf Akzent-Hintergrund (z. B. Tabellenköpfe) dürfen ihre helle Hintergrundfarbe behalten.
• Callout-/Infobox-Hintergründe nicht hartkodieren oder im Dunkelmodus explizit abdunkeln (z. B. auf var(--bg-soft)); farbige Border bleibt.
• Nur innerhalb von @media screen — Druck/PDF bleibt unverändert hell.