166 lines
6.5 KiB
Markdown
166 lines
6.5 KiB
Markdown
```
|
||
MINI-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint)
|
||
|
||
FORMAT
|
||
- A4 Hochformat, 3-4 Seiten
|
||
- @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
|
||
- Footer: Seitenzahl Mitte, Guide-Titel rechts
|
||
|
||
UMFANG (einheitlich mit allen Guide-Stufen)
|
||
- 1 Kapitel (oder besser: 4-6 Sektionen ohne Kapitel-Struktur)
|
||
- ~1500 Wörter Fließtext
|
||
- 5-7 Code-Beispiele (sehr kurz, 2-7 Zeilen)
|
||
- ~15 Min Lesezeit
|
||
- 3-4 Seiten
|
||
|
||
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.
|
||
- Nur innerhalb von @media screen — Druck/PDF bleibt unverändert hell.
|