171 lines
6.7 KiB
Markdown
171 lines
6.7 KiB
Markdown
```
|
||
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.
|