update

templates/Format/MiniGuide.md

@@ -0,0 +1,170 @@
+```
+MINI-GUIDE STYLE (HTML/CSS → PDF via WeasyPrint)
+
+FORMAT
+- A4 portrait, 3-5 pages
+- @page { size: A4; margin: 18mm 18mm 16mm 18mm; }
+- Footer: page number center, guide title right
+
+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
+
+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)
+
+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
+
+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
+
+(This order builds on itself and ends with something meaningful.)
+
+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
+
+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)
+
+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
+
+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 (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..."
+
+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 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 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 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)
+
+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)
+
+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
+
+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
+
+GENERATION WITH FEEDBACK LOOP (max 3 iterations)
+1. Write the HTML
+2. weasyprint file.html file.pdf
+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
+```
+
+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"] { ...dark variable values... }
+    html[data-theme="dark"] body { background: #15171c; }
+  }
+- The app enables it via data-theme="dark" on <html>.
+  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.