diff --git a/templates/Format/Baustein.md b/templates/Format/Baustein.md index 6b4b949..e033aa6 100644 --- a/templates/Format/Baustein.md +++ b/templates/Format/Baustein.md @@ -1,100 +1,109 @@ ``` -BAUSTEIN-CARD-STIL (HTML+CSS, in Browser anzeigbar) +BAUSTEIN CARD STYLE (HTML+CSS, viewable in a browser) -ZWECK -- Einzelner Baustein als kompakte Card-Darstellung -- Schnelles Nachschlagen einzelner Konzepte -- Card ist Teil einer größeren Baustein-Sammlung -- Nicht zum Lernen, sondern zum Wiedererkennen -- Pro Card genau 1 Baustein +PURPOSE +- Single building block ("Baustein") as a compact card +- Quick lookup of individual concepts +- The card is part of a larger collection of building blocks +- Not for learning, but for recognition +- Exactly 1 building block per card FORMAT -- HTML mit eingebettetem CSS -- Im Browser anzeigbar (kein PDF-Output) -- Card auf hellgrauem Hintergrund zentriert +- HTML with embedded CSS +- Viewable in a browser (no PDF output) +- Card centered on a light gray background - Max-width 1000px, padding 28px 36px -- Border-radius 12px, dezenter Schatten -- Page-Hintergrund #f0f0f5 +- Border-radius 12px, subtle shadow +- Page background #f0f0f5 -STRUKTUR — STRIKT NUR DIESE 4 ELEMENTE -1. Titel (h1, fett, ohne Label, ohne Logo) -2. Beschreibung (ein knapper Satz) -3. Zweck (kursiv, grau, ein knapper Satz) -4. Code-Beispiel (das eine relevanteste, mit Mini-Label oben) +STRUCTURE — STRICTLY ONLY THESE 4 ELEMENTS +1. Title (h1, bold, no label, no logo) +2. Description (one concise sentence) +3. Purpose (italic, gray, one concise sentence) +4. Code example (the single most relevant one, with a mini label on top) -KEIN Logo, KEIN "Baustein"-Label, KEIN Sprach-Tag, KEINE Sektion-Überschriften ("Beschreibung", "Zweck", "Relevante Beispiele"), KEINE Info-Blöcke, KEINE Warn/Tip/Note-Boxen, KEINE Meta-Informationen, KEINE Trennlinien zwischen Sektionen. +NO logo, NO "Baustein" label, NO language tag, NO section headings +("Beschreibung", "Zweck", "Relevante Beispiele"), NO info blocks, +NO warn/tip/note boxes, NO meta information, NO divider lines between +sections. -TYPOGRAFIE +TYPOGRAPHY - Body: -apple-system, "Segoe UI", sans-serif, 14px, line-height 1.5 -- Titel h1: 28px, font-weight 800, letter-spacing -0.5px, line-height 1.1 -- Beschreibung: 14px, line-height 1.55 -- Zweck: 14px, italic, color #5a6470 +- Title h1: 28px, font-weight 800, letter-spacing -0.5px, line-height 1.1 +- Description: 14px, line-height 1.55 +- Purpose: 14px, italic, color #5a6470 - Code: "SF Mono", Consolas, monospace, 12px, line-height 1.5 -- Code-Label: 10px, letter-spacing 1px +- Code label: 10px, letter-spacing 1px -FARBEN -- Card-Hintergrund: #ffffff -- Page-Hintergrund: #f0f0f5 +COLORS +- Card background: #ffffff +- Page background: #f0f0f5 - Text: #1a1a1a -- Muted (Zweck): #5a6470 -- Code-Hintergrund: #1e2a3a -- Code-Text: #e6e6e6 -- Syntax-Highlighting: +- Muted (purpose): #5a6470 +- Code background: #1e2a3a +- Code text: #e6e6e6 +- Syntax highlighting: - Keywords (.k): #ff79c6 (pink) - - Variablen (.v): #ffb86c (orange) - - Strings (.s): #f1c40f (gelb) - - Funktionen (.f): #50fa7b (grün) - - Typen (.t): #8be9fd (cyan) - - Kommentare (.c): #6b8aae italic -- Label-Farbe in Code: #8be9fd (cyan) + - Variables (.v): #ffb86c (orange) + - Strings (.s): #f1c40f (yellow) + - Functions (.f): #50fa7b (green) + - Types (.t): #8be9fd (cyan) + - Comments (.c): #6b8aae italic +- Label color in code: #8be9fd (cyan) -INHALTLICHE PRINZIPIEN -- Titel: GELÄUFIGSTER Kurzbegriff, max 1-2 Wörter, kein Präfix, keine Variante - - Gut: "Header", "Variable", "Klasse", "for-Schleife" - - Schlecht: "Überschriften h1–h6", "Variablen-Deklaration mit Typ" -- Beschreibung: WAS macht es mechanisch? 1 Satz, max 5 Wörter, abstrakt/technisch - - Gut: "Definiert eine Überschrift.", "Wiederholt einen Code-Block." - - Schlecht: "Sechs Ebenen von der wichtigsten bis zur untergeordneten Überschrift." -- Zweck: WANN brauche ich das? 1 Satz, max 5 Wörter, situativ/Problem-Trigger - - Gut: "Strukturiert die Seiteninhalte.", "Liste oder Bereich durchgehen." - - Schlecht: "Gliedert Inhalt in Hierarchie für Leser, SEO und Screenreader-Navigation." -- WICHTIG: Beschreibung und Zweck dürfen sich NICHT inhaltlich überschneiden - - Schlecht (tautologisch): Beschreibung "Wiederholt Code." / Zweck "Etwas mehrfach tun." - - Gut (distinkt): Beschreibung "Wiederholt einen Code-Block." / Zweck "Liste oder Bereich durchgehen." -- Beide Sätze: jedes überflüssige Wort raus, keine Aufzählungen, keine Komma-Listen -- Genau EIN Code-Beispiel: das relevanteste / häufigste / typischste -- Beispiel zeigt den Standard-Use-Case, nicht Edge-Cases -- Label über Beispiel: max 2-3 Wörter, einfach, beschreibend - - Gut: "Alle Header", "Zuweisung", "Grund-Regel" - - Schlecht: "Alle Ebenen h1–h6", "Variable mit Typ-Hint deklarieren" +CONTENT PRINCIPLES +- Title: the MOST COMMON short term, max 1-2 words, no prefix, no variant + - Good: "Header", "Variable", "Klasse", "for-Schleife" + - Bad: "Überschriften h1–h6", "Variablen-Deklaration mit Typ" +- Description: WHAT does it do mechanically? 1 sentence, max 5 words, + abstract/technical + - Good: "Definiert eine Überschrift.", "Wiederholt einen Code-Block." + - Bad: "Sechs Ebenen von der wichtigsten bis zur untergeordneten Überschrift." +- Purpose: WHEN do I need this? 1 sentence, max 5 words, + situational/problem trigger + - Good: "Strukturiert die Seiteninhalte.", "Liste oder Bereich durchgehen." + - Bad: "Gliedert Inhalt in Hierarchie für Leser, SEO und Screenreader-Navigation." +- IMPORTANT: description and purpose must NOT overlap in content + - Bad (tautological): description "Wiederholt Code." / purpose "Etwas mehrfach tun." + - Good (distinct): description "Wiederholt einen Code-Block." / purpose "Liste oder Bereich durchgehen." +- Both sentences: cut every superfluous word, no enumerations, no comma lists +- Exactly ONE code example: the most relevant / most common / most typical +- The example shows the standard use case, not edge cases +- Label above the example: max 2-3 words, simple, descriptive + - Good: "Alle Header", "Zuweisung", "Grund-Regel" + - Bad: "Alle Ebenen h1–h6", "Variable mit Typ-Hint deklarieren" -LAYOUT-DETAILS -- Header und Body keine separaten Sektionen, alles in einer Card -- Titel zuerst, darunter direkt Beschreibung, darunter Zweck (mit margin-bottom) -- Margin-bottom Titel: 14px -- Margin-bottom Beschreibung: 6px (eng zum Zweck) -- Margin-bottom Zweck: 22px (Abstand zu Code) -- Code-Block padding: 14px 16px, border-radius 8px +LAYOUT DETAILS +- Header and body are not separate sections, everything in one card +- Title first, directly below it the description, below that the purpose + (with margin-bottom) +- Margin-bottom title: 14px +- Margin-bottom description: 6px (close to the purpose) +- Margin-bottom purpose: 22px (distance to the code) +- Code block padding: 14px 16px, border-radius 8px -CODE-BEISPIEL -- GENAU EIN Beispiel pro Card -- Das relevanteste, typischste, häufigste — nicht Edge-Cases -- Sehr kurz: ideal 3-6 Zeilen, max 8 Zeilen -- Mit kurzem Label oben (2-4 Wörter) -- Syntax-Highlighting durch span-Klassen (.k, .v, .s, etc.) +CODE EXAMPLE +- EXACTLY ONE example per card +- The most relevant, most typical, most common one — not edge cases +- Very short: ideally 3-6 lines, max 8 lines +- With a short label on top (2-4 words) +- Syntax highlighting via span classes (.k, .v, .s, etc.) -HTML-ENTITIES IM CODE (PFLICHT bei HTML/XML/JSX/Vue/JSX-ähnlichem Code) -- Wenn das Code-Beispiel SELBST HTML, XML, JSX oder ähnliche Tag-Syntax zeigt, MÜSSEN spitze Klammern als HTML-Entities geschrieben werden: +HTML ENTITIES IN CODE (MANDATORY for HTML/XML/JSX/Vue/JSX-like code) +- If the code example ITSELF shows HTML, XML, JSX, or similar tag syntax, + angle brackets MUST be written as HTML entities: - `<` → `<` - `>` → `>` - `&` → `&` -- Grund: der Code wird via v-html im Browser gerendert. Rohe `

` werden sonst als echtes DOM-Element interpretiert und verschwinden. -- Gut: `<h1>Text</h1>` -- Schlecht: `

Text

` -- Schlecht: `

Text

` (komplett ohne Spans und ohne Entities) -- Diese Regel gilt NUR für die Inhalte des Code-Beispiels, NICHT für die ``-Wrapper selbst +- Reason: the code is rendered via v-html in the browser. Raw `

` would + otherwise be interpreted as a real DOM element and disappear. +- Good: `<h1>Text</h1>` +- Bad: `

Text

` +- Bad: `

Text

` (entirely without spans and without entities) +- This rule applies ONLY to the contents of the code example, NOT to the + `` wrappers themselves -KONKRETES BEISPIEL — Baustein "Header" (HTML) +CONCRETE EXAMPLE — building block "Header" (HTML) ```json { "title": "Header", @@ -109,35 +118,35 @@ KONKRETES BEISPIEL — Baustein "Header" (HTML) } ``` -VERMEIDEN -- Lange Erklärungstexte -- Mehrere Sätze für Beschreibung oder Zweck -- Performance-Tipps, Trade-Offs, Edge Cases -- Verwandte Bausteine, Varianten, Anti-Patterns -- Tabellen, Listen, Aufzählungen -- Icons, Emojis, Symbole -- Komplexe Code-Beispiele (über 8 Zeilen) -- Mehrere Beispiele (Varianten, Alternativen) +AVOID +- Long explanatory texts +- Multiple sentences for description or purpose +- Performance tips, trade-offs, edge cases +- Related building blocks, variants, anti-patterns +- Tables, lists, enumerations +- Icons, emojis, symbols +- Complex code examples (over 8 lines) +- Multiple examples (variants, alternatives) -THEMENSPEZIFISCHE ANPASSUNGEN -- Bei anderen Sprachen: Syntax-Highlighting-Klassen anpassen -- Titel-Größe und Spacing bleiben gleich -- Card-Layout bleibt gleich -- Inhalte (Beschreibung, Zweck, Beispiel) sprachspezifisch +TOPIC-SPECIFIC ADJUSTMENTS +- For other languages: adapt syntax highlighting classes +- Title size and spacing stay the same +- Card layout stays the same +- Content (description, purpose, example) is language-specific -GENERIERUNG MIT FEEDBACK-LOOP -1. HTML schreiben -2. In Browser anzeigen (Playwright-Screenshot oder direkt) -3. Prüfen: - - Wirklich nur 4 Elemente (Titel, Beschreibung, Zweck, Beispiel)? - - Beschreibung und Zweck je max 5 Wörter? - - Titel max 1-2 Wörter, geläufiger Kurzbegriff? - - Label max 2-3 Wörter, simpel? - - Code-Beispiel unter 8 Zeilen? - - Label über Code-Block kurz und prägnant? - - Card kompakt, kein leerer Raum? - - Ist das gewählte Beispiel wirklich das typischste? - - Bei HTML/XML/JSX-Code: alle `<` und `>` als `<` und `>` geschrieben? -4. Wenn etwas zu viel: weglassen, nicht hinzufügen -5. Bei jeder Iteration prüfen: lässt sich noch was weglassen? -``` \ No newline at end of file +GENERATION WITH FEEDBACK LOOP +1. Write the HTML +2. View in a browser (Playwright screenshot or directly) +3. Check: + - Really only 4 elements (title, description, purpose, example)? + - Description and purpose each max 5 words? + - Title max 1-2 words, common short term? + - Label max 2-3 words, simple? + - Code example under 8 lines? + - Label above the code block short and to the point? + - Card compact, no empty space? + - Is the chosen example really the most typical one? + - For HTML/XML/JSX code: all `<` and `>` written as `<` and `>`? +4. If something is too much: remove it, don't add +5. On every iteration check: can anything else be removed? +``` diff --git a/templates/Format/Cheatsheet.md b/templates/Format/Cheatsheet.md index 37f9664..afb1ae7 100644 --- a/templates/Format/Cheatsheet.md +++ b/templates/Format/Cheatsheet.md @@ -1,123 +1,123 @@ ``` -CHEATSHEET-STIL QUERFORMAT (HTML/CSS → PDF via WeasyPrint) +CHEATSHEET STYLE LANDSCAPE (HTML/CSS → PDF via WeasyPrint) FORMAT -- A4 Querformat (297mm × 210mm) +- A4 landscape (297mm × 210mm) - @page { size: A4 landscape; margin: 0; } -- Padding: 7mm 9mm 18mm 9mm (unten Platz für Footer) -- Position relative für absoluten Footer +- Padding: 7mm 9mm 18mm 9mm (room for the footer at the bottom) +- Position relative for the absolute footer LAYOUT -- Grid: hero (auto) / main (4 Spalten) / footer (absolute) -- Main: 4 Spalten gleich breit, gap 3mm -- Spalten intern: flex-column, gap 3mm -- 8-12 thematische Blöcke verteilt (2-3 pro Spalte) +- Grid: hero (auto) / main (4 columns) / footer (absolute) +- Main: 4 equal-width columns, gap 3mm +- Columns internally: flex-column, gap 3mm +- 8-12 thematic blocks distributed (2-3 per column) -STRUKTUR (in dieser Reihenfolge) -1. Hero: Logo links (15mm), Titel + Untertitel mittig, Version + Stand rechts -2. Main-Grid: 8-12 Blöcke in 4 Spalten -3. Footer: farbige Box mit Quick-Commands + Tag (absolute, unten) +STRUCTURE (in this order) +1. Hero: logo left (15mm), title + subtitle center, version + date right +2. Main grid: 8-12 blocks in 4 columns +3. Footer: colored box with quick commands + tag (absolute, bottom) -UNTERSCHIEDE ZU HOCHFORMAT-CHEATSHEET -- 4 Spalten statt 3 (mehr horizontaler Platz) -- 9-12 Blöcke statt 8-10 -- Footer mit 4 Quick-Commands statt 3 -- Kleinere Schriftgrößen (8pt Body statt 8.5pt) -- Kompaktere Code-Blöcke (6.5pt statt 6.8pt) +DIFFERENCES FROM THE PORTRAIT CHEATSHEET +- 4 columns instead of 3 (more horizontal space) +- 9-12 blocks instead of 8-10 +- Footer with 4 quick commands instead of 3 +- Smaller font sizes (8pt body instead of 8.5pt) +- More compact code blocks (6.5pt instead of 6.8pt) -BLOCK-AUFBAU -- Block-Head: Hauptfarbe-Hintergrund, weißer Text, Icon links (3.5mm) -- Block-Body: weißer Hintergrund, dünner Rand, abgerundet 2mm -- Inhalt: dichte Referenz, nicht Erklärung -- Varianten: Referenz-Tabelle, Code-Block, Kachel-Grid, Plus/Minus +BLOCK STRUCTURE +- Block head: accent-color background, white text, icon left (3.5mm) +- Block body: white background, thin border, rounded 2mm +- Content: dense reference, not explanation +- Variants: reference table, code block, tile grid, plus/minus -FARBEN (max 3 + Neutrals) -- Hauptfarbe: an offizielle Farbe des Themas anlehnen -- Hauptfarbe-Dunkel: dunklere Variante für Headings -- Hauptfarbe-Darker: noch dunkler für Footer -- Akzentfarbe für Plus/Minus: grün/rot -- Hintergrund-Soft: helle Variante der Hauptfarbe -- Code-Hintergrund: #1e2a3a (dunkel) -- Text: #1a1a1a / muted #5a6470 / Linie #d8dde3 +COLORS (max 3 + neutrals) +- Accent color: lean on the topic's official color +- Accent dark: darker variant for headings +- Accent darker: even darker for the footer +- Accent color for plus/minus: green/red +- Background soft: light variant of the accent color +- Code background: #1e2a3a (dark) +- Text: #1a1a1a / muted #5a6470 / line #d8dde3 -TYPOGRAFIE +TYPOGRAPHY - Body: 8pt, line-height 1.35 - Hero h1: 18pt bold -- Block-Head: 8pt bold uppercase, letter-spacing 0.5pt -- Tabellen: 7.5pt, Keys 7pt monospace +- Block head: 8pt bold uppercase, letter-spacing 0.5pt +- Tables: 7.5pt, keys 7pt monospace - Code: 6.5pt monospace, line-height 1.4 -- Inline-Code: 7pt monospace, Hauptfarbe -- Max 3 Schriftgrößen pro Block +- Inline code: 7pt monospace, accent color +- Max 3 font sizes per block ICONS -- SVG inline, stroke statt fill -- 3.5mm in Block-Heads -- 2mm in Tile-Icons (kleiner als Hochformat) -- currentColor für automatische Anpassung +- SVG inline, stroke instead of fill +- 3.5mm in block heads +- 2mm in tile icons (smaller than portrait) +- currentColor for automatic adaptation -BLOCK-TYPEN (für Variation nutzen) -- Referenz-Tabelle: 2-spaltig (Befehl/Methode → Bedeutung) -- Code-Block: vollständiges Beispiel mit Syntax-Highlighting -- Kachel-Grid: 2x4 mit Icons (z.B. Ökosystem) -- Direktiven-Grid: 2-spaltig kompakte Begriffe + Kurzbeschreibung -- Plus/Minus-Split: 2-spaltig (idiomatisch vs vermeiden) +BLOCK TYPES (use for variation) +- Reference table: 2 columns (command/method → meaning) +- Code block: complete example with syntax highlighting +- Tile grid: 2x4 with icons (e.g. ecosystem) +- Directive grid: 2 columns, compact terms + short description +- Plus/minus split: 2 columns (idiomatic vs avoid) -THEMENSPEZIFISCHE ANPASSUNGEN (vor Generierung wählen) -- Hauptfarbe: offizielle Farbe des Themas -- Logo-Buchstabe(n) oder Kürzel -- Version + Stand-Datum -- Block-Auswahl: 8-12 wichtigste Referenz-Themen -- Quick-Commands im Footer: 4 wichtigste Kommandos +TOPIC-SPECIFIC ADJUSTMENTS (choose before generating) +- Accent color: the topic's official color +- Logo letter(s) or abbreviation +- Version + as-of date +- Block selection: the 8-12 most important reference topics +- Quick commands in the footer: the 4 most important commands -VISUELLE ELEMENTE PFLICHT -- Mindestens 1 Code-Block (oft mehrere im Querformat) -- Mindestens 1 Kachel-Grid mit Icons -- Mindestens 1 Plus/Minus-Split -- Footer mit Quick-Commands -- Versionsbadge in Hero +REQUIRED VISUAL ELEMENTS +- At least 1 code block (often several in landscape) +- At least 1 tile grid with icons +- At least 1 plus/minus split +- Footer with quick commands +- Version badge in the hero -VERMEIDEN -- Reine Bullet-Listen ohne Struktur -- Erklärtext (gehört in Guide, nicht Cheatsheet) -- Mehr als 12 Blöcke (überfüllt) -- Mehr als 3 Schriftgrößen -- Vertikal sehr lange Blöcke (Spalten unbalanciert) -- Floats oder absolute positioning (außer für Footer) +AVOID +- Plain bullet lists without structure +- Explanatory text (belongs in a guide, not a cheatsheet) +- More than 12 blocks (overcrowded) +- More than 3 font sizes +- Vertically very long blocks (unbalanced columns) +- Floats or absolute positioning (except for the footer) -GENERIERUNG MIT FEEDBACK-LOOP (max 3 Iterationen) -1. HTML schreiben +GENERATION WITH FEEDBACK LOOP (max 3 iterations) +1. Write the HTML 2. weasyprint file.html file.pdf -3. PDF zu PNG: python -c "from pdf2image import convert_from_path; convert_from_path('file.pdf', dpi=120)[0].save('preview.png')" -4. Preview ansehen mit Read-Tool -5. Prüfen: - - Footer überlappt nicht mit Inhalt? - - 4 Spalten balanciert (ähnliche Höhe)? - - Alle Blöcke vollständig sichtbar? - - Code-Blöcke nicht abgeschnitten? - - Icons rendern? -6. Bei Problemen: Inhalt straffen oder padding-bottom erhöhen, ab Schritt 2 wiederholen -7. Nach max 3 Iterationen ausgeben +3. PDF to PNG: python -c "from pdf2image import convert_from_path; convert_from_path('file.pdf', dpi=120)[0].save('preview.png')" +4. View the preview with the Read tool +5. Check: + - Footer does not overlap the content? + - 4 columns balanced (similar height)? + - All blocks fully visible? + - Code blocks not cut off? + - Icons render? +6. On problems: tighten the content or increase padding-bottom, repeat from step 2 +7. Output after max 3 iterations 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: +DARK MODE (REQUIRED) +- Define all colors exclusively via :root variables + (--ink, --muted, --line, --bg-soft, accent variables). +- Additionally ship a dark-mode block: @media screen { - html[data-theme="dark"] { ...dunkle Variablenwerte... } + html[data-theme="dark"] { ...dark variable values... } html[data-theme="dark"] body { background: #15171c; } } -- Die App aktiviert ihn über data-theme="dark" auf . - 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. +- The app enables it via data-theme="dark" on . + Do NOT use prefers-color-scheme. +- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee), + muted lines (#2c3038). Lift accent colors so headings and links stay + readable on a dark background (check contrast). Elements with light text on + accent backgrounds (e.g. table headers) may keep their light background + color. +- Do not hardcode callout/infobox backgrounds — or darken them explicitly in + dark mode (e.g. to var(--bg-soft)); the colored border stays. +- Only inside @media screen — print/PDF stays light. diff --git a/templates/Format/EndGuide.md b/templates/Format/EndGuide.md index 9a9264c..63becee 100644 --- a/templates/Format/EndGuide.md +++ b/templates/Format/EndGuide.md @@ -1,179 +1,190 @@ -END-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint) +END-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint) FORMAT -- A4 Hochformat, 50–250 Seiten (themenabhängig — kleines Thema kurz, - großes Thema lang; die Seitenzahl folgt aus dem Inventar) +- A4 portrait, 50–250 pages (topic-dependent — small topic short, + large topic long; the page count follows from the inventory) - @page { size: A4; margin: 18mm; } -- Cover-Seite + automatisches Inhaltsverzeichnis -- Footer: Seitenzahl Mitte, " EndGuide" rechts +- Cover page + automatic table of contents +- Footer: page number center, " EndGuide" right -ABDECKUNG (höchste Guide-Stufe) -- ALLE Bausteine des Themas — vollständig, "lieber zu viel als zu wenig". -- Von der ersten Zeile bis zu Experten-Themen (Architektur, Interna, Betrieb — - was immer beim Thema die Expertenstufe ist). -- Aktuelle Version des Themas als Zielversion nennen. +COVERAGE (highest guide tier) +- ALL building blocks of the topic — complete, "rather too much than too little". +- From the very first line up to expert topics (architecture, internals, + operations — whatever the expert tier is for the topic). +- Name the current version of the topic as the target version. -THEMENINVENTAR (verbindlich) -- Das Inventar wird vorab von einem Recherche-Agenten erstellt und mitgeliefert. - Es ist die verbindliche Stoffliste: 1 Inventar-Punkt = 1 EIGENE H2-Sektion - nach dem Muster Titel·Erklärung·Beispiel. -- Punkte beim Schreiben NICHT zusammenfassen, kürzen oder eindampfen — wirkt - das Pensum zu groß, Teil für Teil abarbeiten statt komprimieren. -- Teile und Kapitel aus dem Inventar ableiten: verwandte Punkte zu Kapiteln - gruppieren, Kapitel zu Teilen. Es gibt KEINE Vorgabe-Zahl für Teile/Kapitel. +TOPIC INVENTORY (binding) +- The inventory is produced beforehand by a research agent and supplied with + the task. It is the binding list of material: 1 inventory item = 1 OWN H2 + section following the pattern Title·Explanation·Example. +- Do NOT merge, trim, or condense items while writing — if the workload feels + too large, work part by part instead of compressing. +- Derive parts and chapters from the inventory: group related items into + chapters, chapters into parts. There is NO default number of parts/chapters. -ZIELGRUPPE — VOM ANFÄNGER ZUM EXPERTEN -- Beginnt bei null, steigert sich progressiv über die Teile -- Frühe Teile erklären jeden Begriff; spätere setzen Vorheriges voraus -- Verweise nach hinten ("eigener Teil") erlaubt – der Guide wird durchgelesen - oder nachgeschlagen +TARGET AUDIENCE — FROM BEGINNER TO EXPERT +- Starts at zero, progresses step by step across the parts +- Early parts explain every term; later ones assume what came before +- Forward references ("own part") are allowed — the guide is read cover to + cover or used for lookup -KERNPRINZIP — TITEL · ERKLÄRUNG · BEISPIEL (das definierende Muster) -- JEDES Konzept in genau dieser Reihenfolge: - 1. Titel: reiner Konzept-/Verb-/Typname. Nichts sonst. - 2. Erklärung: 1–3 Sätze Prosa. Nennt die Funktionen/Bausteine und was sie tun. - 3. Beispiel: lauffähiger Code (bzw. konkretes Beispiel) mit sichtbarem - Ergebnis als Kommentar. -- Die Überschrift trägt NIE die Funktionsliste oder die Definition: - - schlecht: "Ersetzen: str_replace & substr_replace" - "object – Instanz einer Klasse" - - gut: "Ersetzen" + Erklärung nennt die Funktionen + Beispiel - "object" + Erklärung "Instanz einer Klasse" + Beispiel +CORE PRINCIPLE — TITLE · EXPLANATION · EXAMPLE (the defining pattern) +- EVERY concept in exactly this order: + 1. Title: pure concept/verb/type name. Nothing else. + 2. Explanation: max. 3 short main clauses, simply worded, no nested + sentences. Names the functions/building blocks and what they do. + Recommendations, real-world problems, and warnings do NOT belong in the + explanation — that is what callouts (tip/warn/note) are for. + 3. Example: runnable code (or a concrete example) with the visible result + as a comment. +- The heading NEVER carries the function list or the definition: + - bad: "Ersetzen: str_replace & substr_replace" + "object – Instanz einer Klasse" + - good: "Ersetzen" + explanation names the functions + example + "object" + explanation "Instanz einer Klasse" + example -INHALTLICHE PRINZIPIEN -- Vollständigkeit: aufzählbare Mengen IMMER komplett (alle Operatoren, alle - Varianten, alle Modi …). Nur sehr große Mengen (z. B. hunderte - Formatzeichen) als Auswahl + Verweis auf die Doku. -- Mechanik zeigen: Beispiele sind echte, lauffähige Mini-Demos MIT Ausgabe – - nicht nur Signaturen oder leere Interfaces. Bei Mustern/Interfaces: - Vertrag + konkrete Implementierung + Aufruf mit sichtbarem Ergebnis. -- Tiefe vor Aufzählung: erst erklären warum/wann, dann zeigen. -- Keine Performance-Zahlen ohne Quelle. +CONTENT PRINCIPLES +- Completeness: enumerable sets ALWAYS complete (all operators, all variants, + all modes …). Only very large sets (e.g. hundreds of format characters) as + a selection + reference to the docs. +- Show the mechanics: examples are real, runnable mini-demos WITH output — + not just signatures or empty interfaces. For patterns/interfaces: + contract + concrete implementation + call with visible result. +- Depth before enumeration: explain why/when first, then show. +- No performance numbers without a source. -CODE-KONVENTIONEN (bei technischen Themen) -- Bezeichner englisch: Variablen, Funktionen, Klassen, Methoden, Konstanten. -- Deutsch bleibt: Fließtext, Überschriften, Code-Kommentare, Ausgabetexte, - Beispieldaten ("Anna", "Köln", "Hallo Welt"). -- Unverändert: themen-/spracheigene Namen (Built-ins, Standard-APIs); - Tabellen-/Spaltennamen in Strings (= Daten, keine Bezeichner). -- Ergebnis-Kommentar an jedem Beispiel: // 19.99 € -- Neutrale Daten: Namen Anna/Ben/Tom, Orte Köln/Hamburg, mail@example.com. - Keine personenbezogenen oder echten Daten. -- Moderne Syntax der aktuellen Zielversion bevorzugen; Versionsabhängiges - kennzeichnen ("seit Version X"). +CODE CONVENTIONS (for technical topics) +- Identifiers in English: variables, functions, classes, methods, constants. +- German stays: prose, headings, code comments, output strings, + sample data ("Anna", "Köln", "Hallo Welt"). +- Unchanged: topic-/language-native names (built-ins, standard APIs); + table/column names in strings (= data, not identifiers). +- Result comment on every example: // 19.99 € +- Neutral data: names Anna/Ben/Tom, places Köln/Hamburg, mail@example.com. + No personal or real data. +- Prefer modern syntax of the current target version; mark version-dependent + features ("seit Version X"). -STRUKTUR -1. Cover: Logo, Titel " — Der EndGuide", Subtitle, Badge - " Teile · Kapitel" (Zahlen aus dem Inventar) -2. Inhaltsverzeichnis (automatisch aus der Struktur erzeugt) -3. Pro Teil: Trennseite (Teil-Nummer · Titel · Beschreibung · Kapitel-Liste) -4. Pro Kapitel: Kapitel-Nummer + Titel, kurzer Lead-Satz, dann H2-Sektionen - nach dem Muster Titel·Erklärung·Beispiel +STRUCTURE +1. Cover: logo, title " — Der EndGuide", subtitle, badge + " Teile · Kapitel" (numbers taken from the inventory) +2. Table of contents (generated automatically from the structure) +3. Per part: divider page (part number · title · description · chapter list) +4. Per chapter: chapter number + title, short lead sentence, then H2 sections + following the pattern Title·Explanation·Example -NUMMERIERUNG -- Teile und Kapitel sind GETRENNTE Zähler. -- Kapitel laufen über den ganzen Guide durch – sie starten NICHT je Teil neu. +NUMBERING +- Parts and chapters are SEPARATE counters. +- Chapters run through the whole guide — they do NOT restart per part. - "Teil 7" ≠ "Kapitel 7". -ELEMENTE -- Fließtext: justify; Erklärungen als Prosa, Aufzählungen sparsam. -- Codeblöcke: dunkler Hintergrund, Syntax-Highlighting, mit Ergebnis-Kommentaren. -- Inline-Code: heller Hintergrund, Hauptfarbe – für jeden Fachbegriff und - Funktionsnamen im Fließtext. -- Callouts in 3 Varianten: tip (✓), warn (!), note (i). Sparsam, höchstens - einer pro Sektion. -- KEINE Übersichts- oder Referenztabellen. Jede Funktion/jedes Feature bekommt - Erklärung + Beispiel inline. +ELEMENTS +- Body text: justify; explanations as prose, bullet lists sparingly. +- Code blocks: dark background, syntax highlighting, with result comments. +- Inline code: light background, accent color — for every technical term and + function name in prose. +- Callouts in 3 flavors: tip (✓), warn (!), note (i). Sparingly, at most + one per section. +- NO overview or reference tables. Every function/feature gets + explanation + example inline. -TYPOGRAFIE & FARBEN (max 3 + Neutrals) -- Hauptfarbe: an offizielle Farbe des Themas anlehnen; dunkle Code-Blöcke - (#1e2a3a-Familie). -- Body Serif; Überschriften Sans-Serif bold; Code Monospace. -- max. 3 Schriftgrößen pro Sektion. +TYPOGRAPHY & COLORS (max 3 + neutrals) +- Accent color: lean on the topic's official color; dark code blocks + (#1e2a3a family). +- Body serif; headings sans-serif bold; code monospace. +- max. 3 font sizes per section. -CALLOUT-NUTZUNG -- tip (✓): Best Practice / Empfehlung. -- warn (!): Sicherheits- oder Stolperfalle. -- note (i): Hintergrund / Abgrenzung. +CALLOUT USAGE +- tip (✓): best practice / recommendation. +- warn (!): security issue or pitfall. +- note (i): background / distinction. +- MANDATORY: sentences like "Empfehlung: …", "In der Praxis problematisch: …", + "Achtung: …" ALWAYS go into the matching callout, never into the running + prose of the explanation. This keeps the explanation short and the hints + scannable. -BUILD-ARCHITEKTUR (strukturgetrieben) -- Eine Quelle der Wahrheit: STRUCTURE in build.py = Liste aus - (Teil-Kicker, Titel, Beschreibung, [Kapiteltitel]) — direkt aus dem - Inventar abgeleitet. Daraus entstehen Reihenfolge, Nummern, - Inhaltsverzeichnis und Trennseiten automatisch. -- Inhalt in Modulen content_partN.py: CHAPTERS = { "Kapiteltitel": body_html }. - Teil für Teil schreiben — nie den ganzen Guide in einem Stück. Nach jedem - Teil: H2-Sektionen gegen die Inventar-Punkte des Teils zählen, Fehlendes - sofort ergänzen, erst dann den nächsten Teil beginnen. -- build.py meldet am Ende die Gesamtzahl der H2-Sektionen; sie muss der - Anzahl der Inventar-Punkte entsprechen. -- Highlight-Span-Klassen im Code: - c=Kommentar, k=Keyword, s=String/Zahl, f=Funktion, - t=Typ/Klasse/Konstante, v=Variable, a=Attribut. - Inline-Code im Text: . -- Escaping im Code: < > & als < > & (z. B. ->, =>, &&). -- scrub() filtert beim Bauen personenbezogene Reste (Namen/Orte/Mails) heraus. +BUILD ARCHITECTURE (structure-driven) +- One source of truth: STRUCTURE in build.py = list of + (part kicker, title, description, [chapter titles]) — derived directly from + the inventory. Order, numbers, table of contents, and divider pages are + generated from it automatically. +- Content in modules content_partN.py: CHAPTERS = { "chapter title": body_html }. + Write part by part — never the whole guide in one go. After each part: + count the H2 sections against that part's inventory items, add anything + missing immediately, only then start the next part. +- build.py reports the total number of H2 sections at the end; it must match + the number of inventory items. +- Highlight span classes in code: + c=comment, k=keyword, s=string/number, f=function, + t=type/class/constant, v=variable, a=attribute. + Inline code in prose: . +- Escaping in code: < > & as < > & (e.g. ->, =>, &&). +- scrub() filters out personal leftovers (names/places/emails) during build. -VERMEIDEN -- Feste Teile-/Kapitel-/Seitenzahlen als Ziel (der Umfang folgt aus dem - Inventar, nicht umgekehrt). -- Inventar-Punkte zusammenfassen oder weglassen. -- Funktionsliste oder Definition in der Überschrift (Titel bleibt rein). -- Übersichts-/Referenztabellen ohne Erklärtext. -- Deutsche Code-Bezeichner. -- Personenbezogene oder echte Daten. -- Unvollständige aufzählbare Mengen. -- Reine Interface-/Signatur-Stubs ohne Aufruf + Ausgabe. -- Performance-Zahlen ohne Quelle. -- Codeblock oder Callout über einen Seitenumbruch zerrissen +AVOID +- Fixed part/chapter/page counts as a target (scope follows from the + inventory, not the other way around). +- Merging or dropping inventory items. +- Function list or definition in the heading (the title stays pure). +- Explanations longer than 3 sentences or with nested sentences. +- Recommendations/warnings in running prose instead of in a callout. +- Overview/reference tables without explanatory text. +- German code identifiers. +- Personal or real data. +- Incomplete enumerable sets. +- Pure interface/signature stubs without call + output. +- Performance numbers without a source. +- Code block or callout torn across a page break (page-break-inside: avoid). -GENERIERUNG & PRÜFUNG -1. Inventar lesen, STRUCTURE daraus ableiten. -2. python3 build.py → guide.html (meldet Kapitel/Teile + Sektionen) +GENERATION & VERIFICATION +1. Read the inventory, derive STRUCTURE from it. +2. python3 build.py → guide.html (reports chapters/parts + sections) 3. weasyprint guide.html guide.pdf -4. Verifizieren — die Sollwerte kommen aus dem Inventar: - - grep -c 'toc-part' == Anzahl Teile in STRUCTURE - - grep -c 'chapter-num' == Anzahl Kapitel in STRUCTURE - - grep -c '' == 0 - - keine echten Namen/Orte/Mails - - Seitenzahl (pdfinfo) im Rahmen 50–250 -5. Stichproben rendern (pdftoppm) und ansehen: - - Überschrift = reiner Titel, Erklärung darunter, dann Beispiel? - - Code englisch, Erklärung und Kommentare deutsch? - - Codeblöcke/Callouts nicht über Seitenumbruch zerrissen? - - Cover, Inhaltsverzeichnis und Teil-Trennseiten korrekt? + - no real names/places/emails + - page count (pdfinfo) within the 50–250 range +5. Render samples (pdftoppm) and inspect: + - Heading = pure title, explanation below it, then the example? + - Code in English, explanation and comments in German? + - Code blocks/callouts not torn across page breaks? + - Cover, table of contents, and part dividers correct? -CHECKLISTE PRO ABSCHNITT -- [ ] Überschrift ist ein reiner Titel (keine Funktionsliste, keine Definition) -- [ ] Erklärung in Prosa vorhanden, nennt die Bausteine -- [ ] lauffähiges Beispiel mit Ergebnis-Kommentar -- [ ] keine Tabelle -- [ ] englische Bezeichner, deutsche Erklärung/Kommentare/Daten -- [ ] aufzählbare Menge vollständig -- [ ] neutrale Beispieldaten +CHECKLIST PER SECTION +- [ ] Heading is a pure title (no function list, no definition) +- [ ] Explanation in prose present, names the building blocks +- [ ] Explanation max. 3 short main clauses, no nested sentences +- [ ] Recommendations/warnings as callout, not in running prose +- [ ] runnable example with result comment +- [ ] no table +- [ ] English identifiers, German explanation/comments/data +- [ ] enumerable set complete +- [ ] neutral sample data INSTALLATION - pip install weasyprint - apt install poppler-utils (pdfinfo, pdftoppm, pdftotext) -DARKMODE (PFLICHT) -- Alle Farben ausschließlich über :root-Variablen definieren - (--ink, --muted, --line, --bg-soft, Akzent-Variablen). -- Zusätzlich einen Dunkelmodus-Block ausliefern: +DARK MODE (REQUIRED) +- Define all colors exclusively via :root variables + (--ink, --muted, --line, --bg-soft, accent variables). +- Additionally ship a dark-mode block: @media screen { - html[data-theme="dark"] { ...dunkle Variablenwerte... } + html[data-theme="dark"] { ...dark variable values... } html[data-theme="dark"] body { background: #15171c; } } -- Die App aktiviert ihn über data-theme="dark" auf . - 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. +- The app enables it via data-theme="dark" on . + Do NOT use prefers-color-scheme. +- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee), + muted lines (#2c3038). Lift accent colors so headings and links stay + readable on a dark background (check contrast). Elements with light text on + accent backgrounds (e.g. table headers) may keep their light background + color. +- Do not hardcode callout/infobox backgrounds — or darken them explicitly in + dark mode (e.g. to var(--bg-soft)); the colored border stays. +- Only inside @media screen — print/PDF stays light. diff --git a/templates/Format/Guide.md b/templates/Format/Guide.md index 22a9a87..7913422 100644 --- a/templates/Format/Guide.md +++ b/templates/Format/Guide.md @@ -47,7 +47,8 @@ A **topic inventory** is produced beforehand by a research agent and supplied to - Open each chapter with a one- or two-sentence **lead** (`.lead`) that frames why the topic matters. - Explain each new term the first time it appears. Assume an intelligent reader who is new to *this* subject. - Prefer **short, concrete examples** over abstract description. For technical topics that means small code snippets; for non-technical topics it means worked examples, sample dialogues, before/after comparisons, small tables, checklists, or step lists. -- Use **callouts** to highlight tips, warnings, side-notes, and deeper digressions — not more than one or two per chapter. +- **Explanations are short and simple**: max. 3 short main clauses per concept, no nested sentences. Plain language over precision-flexing. +- Use **callouts** to highlight tips, warnings, side-notes, and deeper digressions — not more than one or two per chapter. Sentences like "Empfehlung: …", "In der Praxis problematisch: …", "Achtung: …" ALWAYS go into the matching callout (tip/warn/note), never into running explanation text. - Keep prose tight. This is a reference people skim and return to, not an essay. --- @@ -752,6 +753,7 @@ Example (PHP-flavored, but the pattern is language-agnostic): - [ ] TOC lists every part and every chapter, sequential numbering - [ ] Each part has a divider; each chapter starts with `.chapter-head` + `.lead` - [ ] Callouts used sparingly (≤ ~2 per chapter), correct flavor +- [ ] Explanations ≤ 3 short main clauses; recommendations/warnings live in callouts, not prose - [ ] Tables for comparisons/lists; code blocks only if technical, short, escaped - [ ] Prose in the reader's language; terms explained on first use - [ ] Built with WeasyPrint and **visually verified** by rendering pages diff --git a/templates/Format/MiniGuide.md b/templates/Format/MiniGuide.md index f9964f7..57ed49f 100644 --- a/templates/Format/MiniGuide.md +++ b/templates/Format/MiniGuide.md @@ -1,168 +1,170 @@ ``` -MINI-GUIDE-STIL (HTML/CSS → PDF via WeasyPrint) +MINI-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint) FORMAT -- A4 Hochformat, 3-5 Seiten +- A4 portrait, 3-5 pages - @page { size: A4; margin: 18mm 18mm 16mm 18mm; } -- Footer: Seitenzahl Mitte, Guide-Titel rechts +- Footer: page number center, guide title right -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 +COVERAGE (lowest guide tier) +- ALL core building blocks of the topic — what you need to get started. + Which ones those are depends on the topic. +- The topic inventory is produced beforehand by a research agent and + supplied. It is binding: every item gets a section. +- Sections without chapter structure; code examples very short (2-7 lines) +- ~15-25 min reading time, 3-5 pages — this upper limit always applies -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) +TARGET AUDIENCE — COMPACT BEGINNER INTRO +- Real beginners with no programming experience in the topic +- Assumes only general understanding ("what is programming") +- Terms are explained on first appearance +- NO language-character overview for experienced developers +- NO advanced features (even if cool and short) -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 +CONTENT PRINCIPLES +- Show only absolute basics +- Topics someone can reproduce themselves after 15 min +- No tooling complexity (package managers, build systems, compilers) +- No language specialties (type systems, decorators, generics) +- No OOP if possible (or only the most trivial form) +- Depth of explanation before breadth of features +- Better 5 concepts thoroughly than 15 superficially -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 +TYPICAL 5-SECTION STRUCTURE +1. Starting the language — installation, first file, first program +2. Variables — concept + 2-3 basic types +3. Control flow — if/else with a simple example +4. Lists + iteration — array + loop +5. Functions — declaration + call + return value -(Diese Reihenfolge baut aufeinander auf und endet mit etwas Sinnvollem.) +(This order builds on itself and ends with something meaningful.) -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 +STRUCTURE +1. Compact head: logo left (16mm), title + subtitle center, badge + time right +2. Gap opener: opening question, italic and framed, low-threshold +3. 4-6 H2 sections with explanatory text + code example + optional 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) +ELEMENTS +- Body text: justify with hyphenation +- Code blocks: dark background, syntax highlighting, very short (2-7 lines) +- Inline code: light background, accent color +- Tables: only if truly necessary (comparison operators etc.) +- Callouts in 3 flavors: tip (green), warn (red), note (accent color) -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 +TYPOGRAPHY +- Body: 10.5pt serif (Charter), line-height 1.55 +- Head h1: 20pt sans-serif bold +- H2 section: 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 +COLORS (max 3 + neutrals) +- Accent color: strong, leaning on the topic's official color +- Accent dark: darker variant for accents +- Background soft: light variant of the accent color +- Code background: #1e2a3a +- Text: #1a1a1a / muted #5a6470 / line #d8dde3 +- Callout colors: green/red/accent -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: +GAP OPENER (REQUIRED) +- Italic, framed with an accent-color border +- Low-threshold question that the guide answers +- Sparks interest with a relevant statistic or practical angle +- NO technical terms that have not been explained yet +- Examples: - "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 +EXPLANATION DEPTH PER CONCEPT +- Name the concept (e.g. "Variable") +- Explain in one sentence what it is +- Code example with comments +- Mention language quirks (e.g. "in PHP beginnen Variablen mit $") +- NO reference to concepts that come later -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 USAGE +- tip (green): practice suggestion at the end, encouraging +- warn (red): beginner pitfalls ("= vs ==", "vergessenes Semikolon") +- note (accent): background info, explanation of a language quirk -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) +CALLOUT CSS IMPORTANT +- .callout-body > b:first-child with display:block for the label +- NOT .callout-body b globally with display:block (destroys 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) +GAP CSS IMPORTANT +- .gap > b:first-child with display:block for the "FRAGE ZUM EINSTIEG" label +- NOT .gap b globally with display:block (destroys inline bold in the + question 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) +TOPIC-SPECIFIC ADJUSTMENTS (choose before generating) +- Accent color: the topic's official color +- Logo letter(s) or abbreviation +- Welcome statistic in the gap opener +- Choose 4-6 beginner topics (see standard structure) -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 +REQUIRED ELEMENTS +- 1 gap opener at the start +- 5-7 code examples (short, 2-7 lines, beginner-friendly) +- At least 1 callout (often: warn for a pitfall, tip for practice at the end) +- Inline code for technical terms -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 +AVOID +- TOC or cover (oversized for 15 min) +- Introductory filler ("In diesem Mini-Guide lernen wir...") +- Claims of completeness (belongs in a larger guide) +- Reference tables without explanatory text (belongs in a cheatsheet) +- Recall or next-step at the end (a mini-guide ends with content) +- Topics that are advanced (even if cool): + - Type systems, type hints, generics + - OOP features (except the most trivial form) + - Tooling (package managers, build, linting) + - Language specialties (PHP: strict_types, readonly, Composer, PSR-4) +- page break in the middle of a code block or callout + (page-break-inside: avoid) +- More than 3 font sizes per section +- Floats or absolute positioning (breaks in WeasyPrint) +- Technical terms without explanation +- References to concepts that come later +- Edge cases and "but" sentences -GENERIERUNG MIT FEEDBACK-LOOP (max 3 Iterationen) -1. HTML schreiben +GENERATION WITH FEEDBACK LOOP (max 3 iterations) +1. Write the HTML 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 +3. PDF to PNGs: convert all pages +4. View all pages +5. Check: + - Head clean (logo does not overlap the title)? + - Code blocks not torn across page breaks? + - Callouts fully visible? + - Inline bolds in callouts/gap correct (not rendered as blocks)? + - Footer with page number correct? + - Would a real beginner understand this? + - Were all technical terms explained on first appearance? +6. On problems: fix, repeat from step 2 +7. Output after max 3 iterations 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: +DARK MODE (REQUIRED) +- Define all colors exclusively via :root variables + (--ink, --muted, --line, --bg-soft, accent variables). +- Additionally ship a dark-mode block: @media screen { - html[data-theme="dark"] { ...dunkle Variablenwerte... } + html[data-theme="dark"] { ...dark variable values... } html[data-theme="dark"] body { background: #15171c; } } -- Die App aktiviert ihn über data-theme="dark" auf . - 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. +- The app enables it via data-theme="dark" on . + Do NOT use prefers-color-scheme. +- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee), + muted lines (#2c3038). Lift accent colors so headings and links stay + readable on a dark background (check contrast). Elements with light text on + accent backgrounds (e.g. table headers) may keep their light background + color. +- Do not hardcode callout/infobox backgrounds — or darken them explicitly in + dark mode (e.g. to var(--bg-soft)); the colored border stays. +- Only inside @media screen — print/PDF stays light. diff --git a/templates/Format/OnePager.md b/templates/Format/OnePager.md index 7bbaf8f..5b30b3d 100644 --- a/templates/Format/OnePager.md +++ b/templates/Format/OnePager.md @@ -1,115 +1,115 @@ ``` -ONEPAGER-STIL QUERFORMAT (HTML/CSS → PDF via WeasyPrint) +ONEPAGER STYLE LANDSCAPE (HTML/CSS → PDF via WeasyPrint) FORMAT -- A4 Querformat (297mm × 210mm) +- A4 landscape (297mm × 210mm) - @page { size: A4 landscape; margin: 0; } - Padding: 9mm 11mm 9mm 11mm LAYOUT -- Grid: hero+stats (auto) / divider / main (1fr, 3 Spalten) / footer (absolute) -- Stats-Bar in Hero integriert (rechts), spart vertikalen Platz -- Main: 3 Spalten gleich breit, gap 4mm -- Spalten intern: flex-column, gap 4mm -- 6 thematische Blöcke verteilt (2 pro Spalte) +- Grid: hero+stats (auto) / divider / main (1fr, 3 columns) / footer (absolute) +- Stats bar integrated into the hero (right), saves vertical space +- Main: 3 equal-width columns, gap 4mm +- Columns internally: flex-column, gap 4mm +- 6 thematic blocks distributed (2 per column) -STRUKTUR (in dieser Reihenfolge) -1. Hero: Logo links (22mm), Titel + Untertitel mittig, 4 Stats rechts -2. Divider: 1.5pt schwarze Linie -3. Main-Grid: 6 Blöcke in 3 Spalten -4. Footer: farbige Box mit Kernaussage + Tag (absolute, unten) +STRUCTURE (in this order) +1. Hero: logo left (22mm), title + subtitle center, 4 stats right +2. Divider: 1.5pt black line +3. Main grid: 6 blocks in 3 columns +4. Footer: colored box with key message + tag (absolute, bottom) -UNTERSCHIEDE ZU HOCHFORMAT -- 3 Spalten statt 2 (mehr horizontaler Platz) -- 6 Blöcke statt 4-5 -- Stats integriert in Hero statt eigene Zeile -- Kleinere Schriftgrößen (9.5pt Body statt 10pt) -- Kompaktere Code-Blöcke (7pt statt 7.5pt) +DIFFERENCES FROM PORTRAIT +- 3 columns instead of 2 (more horizontal space) +- 6 blocks instead of 4-5 +- Stats integrated into the hero instead of their own row +- Smaller font sizes (9.5pt body instead of 10pt) +- More compact code blocks (7pt instead of 7.5pt) -BLOCK-AUFBAU -- Titel: 9.5pt bold uppercase, Icon links, Hauptfarbe-Unterstreichung 2pt -- Inhalt: visuell, nicht reine Textbullets -- Varianten: Icon-Liste, Code-Block, Kachel-Grid, Plus/Minus-Spalten, Type-Grid +BLOCK STRUCTURE +- Title: 9.5pt bold uppercase, icon left, accent-color underline 2pt +- Content: visual, not plain text bullets +- Variants: icon list, code block, tile grid, plus/minus columns, type grid -FARBEN (max 3 + Neutrals) -- Hauptfarbe: an offizielle Farbe des Themas anlehnen -- Hauptfarbe-Dunkel: für Headings -- Hauptfarbe-Darker: für Footer -- Akzentfarbe: kontrastierend -- Hintergrund-Soft: helle Variante der Hauptfarbe -- Code-Hintergrund: #1e2a3a -- Text: #1a1a1a / muted #5a6470 / Linie #e5e5e5 +COLORS (max 3 + neutrals) +- Accent color: lean on the topic's official color +- Accent dark: for headings +- Accent darker: for the footer +- Accent color: contrasting +- Background soft: light variant of the accent color +- Code background: #1e2a3a +- Text: #1a1a1a / muted #5a6470 / line #e5e5e5 -TYPOGRAFIE +TYPOGRAPHY - Body: 9.5pt, line-height 1.4 - Hero h1: 20pt bold -- Block-Titel: 9.5pt bold uppercase, letter-spacing 0.5pt -- Stats-Zahl: 14pt bold, Label 6.5pt uppercase -- Code: 7pt monospace, dunkler Hintergrund -- Feature-Text: 8.5pt -- Max 3 Schriftgrößen pro Block +- Block title: 9.5pt bold uppercase, letter-spacing 0.5pt +- Stats number: 14pt bold, label 6.5pt uppercase +- Code: 7pt monospace, dark background +- Feature text: 8.5pt +- Max 3 font sizes per block ICONS -- SVG inline, stroke statt fill -- 4mm in Block-Titeln (kleiner als Hochformat wegen kompakter Layout) -- 2.8mm in Kachel-Icons -- currentColor für automatische Anpassung +- SVG inline, stroke instead of fill +- 4mm in block titles (smaller than portrait due to compact layout) +- 2.8mm in tile icons +- currentColor for automatic adaptation -THEMENSPEZIFISCHE ANPASSUNGEN (vor Generierung wählen) -- Hauptfarbe: offizielle Farbe des Themas -- Logo-Buchstabe(n) oder Kürzel -- 4 Stats: themen-relevante Zahlen -- Block-Auswahl: 6 wichtigste Aspekte für Erstübersicht +TOPIC-SPECIFIC ADJUSTMENTS (choose before generating) +- Accent color: the topic's official color +- Logo letter(s) or abbreviation +- 4 stats: topic-relevant numbers +- Block selection: the 6 most important aspects for a first overview -VISUELLE ELEMENTE PFLICHT -- Mindestens 1 Code-Block -- Mindestens 1 Kachel-Grid mit Icons (Ökosystem) -- Mindestens 1 Plus/Minus-Split (Modern vs Legacy o.ä.) -- Footer als farbige Box (visueller Anker) -- Stats-Bar im Hero +REQUIRED VISUAL ELEMENTS +- At least 1 code block +- At least 1 tile grid with icons (ecosystem) +- At least 1 plus/minus split (modern vs legacy etc.) +- Footer as a colored box (visual anchor) +- Stats bar in the hero -VERMEIDEN -- Reine Bullet-Listen in jedem Block -- Mehr als 6 Hauptblöcke (Querformat hat eh schon mehr Platz) -- Mehr als 3 Schriftgrößen -- Marketing-Floskeln in Hero -- Floats oder absolute positioning (außer für Footer) -- Vertikal sehr lange Blöcke (würden Spalten unbalanciert machen) +AVOID +- Plain bullet lists in every block +- More than 6 main blocks (landscape already has more space) +- More than 3 font sizes +- Marketing filler in the hero +- Floats or absolute positioning (except for the footer) +- Vertically very long blocks (would unbalance the columns) -GENERIERUNG MIT FEEDBACK-LOOP (max 3 Iterationen) -1. HTML schreiben +GENERATION WITH FEEDBACK LOOP (max 3 iterations) +1. Write the HTML 2. weasyprint file.html file.pdf -3. PDF zu PNG: python -c "from pdf2image import convert_from_path; convert_from_path('file.pdf', dpi=120)[0].save('preview.png')" -4. Preview ansehen mit Read-Tool -5. Prüfen: - - Stats-Bar überlappt nicht mit Titel? - - 3 Spalten balanciert (ähnliche Höhe)? - - Footer nicht abgeschnitten? - - Code-Block lesbar? - - Alle Icons rendern? -6. Bei Problemen: fixen, ab Schritt 2 wiederholen -7. Nach max 3 Iterationen ausgeben +3. PDF to PNG: python -c "from pdf2image import convert_from_path; convert_from_path('file.pdf', dpi=120)[0].save('preview.png')" +4. View the preview with the Read tool +5. Check: + - Stats bar does not overlap the title? + - 3 columns balanced (similar height)? + - Footer not cut off? + - Code block readable? + - All icons render? +6. On problems: fix, repeat from step 2 +7. Output after max 3 iterations 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: +DARK MODE (REQUIRED) +- Define all colors exclusively via :root variables + (--ink, --muted, --line, --bg-soft, accent variables). +- Additionally ship a dark-mode block: @media screen { - html[data-theme="dark"] { ...dunkle Variablenwerte... } + html[data-theme="dark"] { ...dark variable values... } html[data-theme="dark"] body { background: #15171c; } } -- Die App aktiviert ihn über data-theme="dark" auf . - 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. +- The app enables it via data-theme="dark" on . + Do NOT use prefers-color-scheme. +- Dark values: dark backgrounds (#15171c / #23262e), light text (#e6e8ee), + muted lines (#2c3038). Lift accent colors so headings and links stay + readable on a dark background (check contrast). Elements with light text on + accent backgrounds (e.g. table headers) may keep their light background + color. +- Do not hardcode callout/infobox backgrounds — or darken them explicitly in + dark mode (e.g. to var(--bg-soft)); the colored border stays. +- Only inside @media screen — print/PDF stays light. diff --git a/templates/Format/Suche.md b/templates/Format/Suche.md index b0706d8..41940bf 100644 --- a/templates/Format/Suche.md +++ b/templates/Format/Suche.md @@ -1,43 +1,44 @@ -Du erstellst eine Themen-Taxonomie. Ein Nutzer beschreibt ein Problem oder -Lernziel. Leite daraus 7 THEMEN-NAMEN ab, zu denen jeweils ein vollständiger -Lern-Guide erstellt werden kann, der das Thema komplett vermittelt, um das -Problem zu lösen. +You create a topic taxonomy. A user describes a problem or learning goal. +Derive 7 TOPIC NAMES from it, each of which could become a complete learning +guide that fully teaches the topic in order to solve the problem. -Problem des Nutzers: +The user's problem: {problem} -BEREITS VORHANDENE THEMEN (Referenz – diese NICHT erneut vorschlagen): +ALREADY EXISTING TOPICS (reference — do NOT propose these again): {existing} -GRUNDPRINZIP – MECE (Mutually Exclusive, Collectively Exhaustive): -Die Themen müssen sich gegenseitig ausschließen (kein Thema ist ein Unterthema -eines anderen, keine inhaltliche Überschneidung) und zusammen das Problem -sinnvoll abdecken. Alle Themen stehen auf der GLEICHEN Abstraktionsebene – -gleichrangige Hauptthemen, niemals eine Mischung aus Ober- und Unterthemen. +CORE PRINCIPLE — MECE (Mutually Exclusive, Collectively Exhaustive): +The topics must be mutually exclusive (no topic is a subtopic of another, no +content overlap) and together cover the problem sensibly. All topics sit on +the SAME level of abstraction — equal-ranking main topics, never a mix of +parent and child topics. -Stil der Themen-Namen: -- KURZ und prägnant: 1–3 Wörter, wie ein Buchregal-Etikett, KEIN Satz. -- Thema VOLLSTÄNDIG benennen, keine Teilmenge. Jeder Guide deckt sein Thema - komplett ab, daher KEINE Zusätze wie "Grundlagen", "Basics", "Einführung". - Richtig: "CSS" — Falsch: "CSS Grundlagen". -- KEIN Doppelpunkt, KEINE Erklärung, KEINE Marketing-Sprache im Titel. -- Beispiele für guten Stil: "HTML", "CSS", "JavaScript", "Deployment", "Git". +Style of the topic names: +- SHORT and concise: 1–3 words, like a bookshelf label, NOT a sentence. +- Name the topic COMPLETELY, not a subset. Each guide covers its topic in + full, so NO additions like "Grundlagen", "Basics", "Einführung". + Right: "CSS" — Wrong: "CSS Grundlagen". +- NO colon, NO explanation, NO marketing language in the title. +- Examples of good style: "HTML", "CSS", "JavaScript", "Deployment", "Git". -Inhaltliche Anforderungen: -- Treffe das konkrete Problem, nicht nur das Oberthema. -- Bei vagem Problem: Themen für die wahrscheinlichsten Interpretationen. -- Die Themen müssen NICHT existieren – wähle gut benennbare, präzise Titel. +Content requirements: +- Address the concrete problem, not just the broad subject area. +- For a vague problem: topics for the most likely interpretations. +- The topics do NOT have to exist already — choose well-nameable, + precise titles. -PFLICHT-PRÜFSCHRITT vor der Ausgabe (intern, NICHT mit ausgeben): -Erstelle zuerst einen Entwurf von 7 Themen. Prüfe dann JEDES Paar (A, B): -Könnte Thema A sinnvoll als Kapitel im Guide zu Thema B behandelt werden? -Wenn ja, verletzt das die MECE-Regel → ersetze A durch ein gleichrangiges, -disjunktes Thema. Wiederhole, bis kein Thema mehr ein Unterthema eines anderen -ist. Beispiele für Verstöße: "Responsive Design" gehört in "CSS"; -"Domain & DNS" gehört in "Deployment". Gib erst danach das finale Set aus. +MANDATORY CHECK before output (internal, do NOT include in the output): +First draft 7 topics. Then check EVERY pair (A, B): +Could topic A reasonably be covered as a chapter inside the guide for +topic B? If yes, that violates the MECE rule → replace A with an +equal-ranking, disjoint topic. Repeat until no topic is a subtopic of +another. Examples of violations: "Responsive Design" belongs in "CSS"; +"Domain & DNS" belongs in "Deployment". Only then output the final set. -AUSGABE: -Antworte AUSSCHLIESSLICH mit einem JSON-Array von 7 Elementen. Jedes Element: -- "title": kurzer Themen-Name (max. 30 Zeichen, 1–3 Wörter) -- "reason": ein Satz, wie dieser Guide das Problem konkret löst -Kein weiterer Text, nur das JSON-Array. \ No newline at end of file +OUTPUT: +Respond EXCLUSIVELY with a JSON array of 7 elements. Each element: +- "title": short topic name (max. 30 characters, 1–3 words) +- "reason": one sentence describing how this guide concretely solves the problem +Write "title" and "reason" in German. +No other text, only the JSON array.