``` # Guide Style System — Authoring & Build Specification This document is a **complete, self-contained specification** for producing a polished, book-style guide as a single HTML file that renders to a clean A4 PDF. It is **topic-neutral**: use it for programming subjects (PHP, Godot, Blender) and equally for non-technical ones (nutrition, finance, psychology, communication, language learning, …). You will normally be given two things: this specification and possibly one reference HTML file built with it. From those alone you must be able to: 1. Gather the subject knowledge yourself (research as needed). 2. Decide a structure (parts → chapters). 3. Write a single HTML file that embeds the CSS from this document verbatim. 4. Convert that HTML to PDF. Follow this spec exactly. The visual identity depends on small details (spacing, weights, the single accent color), so do not improvise the CSS. You **do** have full freedom over content, structure, length, and which optional building blocks you use. --- ## 1. Output contract - **One HTML file**, self-contained: a single `
…
…
…
…
…
…
…
``` You may generate this HTML however you like — by hand, or with a small script that concatenates strings. A script helps for long guides because it keeps each chapter in its own readable chunk. If you use a script, **the script is throwaway**; the deliverable is the HTML (and the PDF), not the script. --- ## 6. The building blocks Below is the exact markup for every block. Copy these shapes; fill in content. ### 6.1 Cover ```html

MAIN TITLESubtitle line

One or two sentences describing what the guide covers and who it is for.
N Parts · M Chapters Edition / version · Year Focus: …
◆
``` - **`.cover-logo`** — 1–4 characters or a single symbol that evokes the topic. Examples: `php`, `gd` (Godot), a Blender-style `b`, `€` (finance), `Ψ` (psychology), `EN` (English), `🍎` is **not** allowed (no emoji in the logo — keep it crisp). Prefer short letterforms or a geometric glyph (`◆ ● ▲ ■`). - **`.cover h1`** — the big title. The `` is an optional lighter, smaller second line (e.g. `PHP` then `The Complete Guide`). Drop the span for a single-line title. - **`.cover-deco`** — a giant, very faint background glyph in the bottom-right. Pick something topic-flavored: a code fragment (``s. Use it to state scope (parts/chapters), edition/year, and the focus. This is where you set the reader's expectations about length and depth. ### 6.2 Table of contents List every part, and under it every chapter, numbered sequentially across the whole guide. There are **no real page numbers** (WeasyPrint does not back-fill them here), so the `.toc-page` element is optional — omit it, or use it only if you maintain numbers yourself. The dotted leader still looks right without a trailing number. ```html

Contents

Part 1 · Fundamentals
1 First chapter title
2 Second chapter title
Part 2 · Going Deeper
3 …
``` ### 6.3 Part divider One full page that introduces a part. The chapter list mirrors the TOC entries for that part. ```html
Part 1

Fundamentals

Italic one-liner describing the arc of this part.
1 · First chapter 2 · Second chapter 3 · Third chapter
``` ### 6.4 Chapter The `.chapter-head` is special: its text is captured into the **running header** at the top-right of every page in that chapter (via `string-set: chaptertitle content()`). Note that `content()` concatenates the text of **all** children, so the chapter-number span and the title run together in the header (e.g. "Chapter 1Title"). For a clean separator, end the `.chapter-num` text with a trailing separator such as `Chapter 1 ·` (trailing space + middot) — or accept the run-on; both are acceptable. Either way keep the chapter `

` reasonably short so it fits on one header line. ```html
Chapter 1

Chapter title

Framing sentence(s) — why this matters.

A section

Body text. Use bold for the key term in a sentence. Inline monospace like term works for any short literal — a command, a key name, a nutrient, a chord, a German case.

A sub-section

…

``` ### 6.5 Callouts Four flavors. Each has a short uppercase label as the **first ``** inside `.callout-body`, then body text. The icon column holds one glyph. ```html
✓
LABELBody text giving a practical tip.
!
LABELBody text warning about a trap.
i
LABELBody text for a neutral side note.
◆
LABELBody text for an optional deeper dive.
``` Meaning of each flavor (topic-independent): |Flavor|Color|Use for| |---|---|---| |`tip`|green, ✓|best practice, a recommendation, a shortcut| |`warn`|red, !|a common mistake, risk, or thing to avoid| |`note`|accent, i|a neutral aside, clarification, context| |`deep`|gold, ◆|optional depth: history, edge case, advanced detail| Standard icon entities: tip `✓` (✓), warn `!`, note `i`, deep `◆` (◆). You may substitute a more fitting single glyph, but keep it one character. ### 6.6 Tables Plain `` with a header row. The styling (accent header, zebra rows) is automatic. Keep tables to a few columns so they fit A4 width. ```html
Column AColumn B
valuevalue
valuevalue
``` Tables are one of the most useful blocks for **non-technical** topics too: nutrient comparisons, vocabulary lists, pros/cons, decision matrices, dosage/timing, term glossaries. --- ## 7. Code blocks — optional, technical topics only The dark `
` block and the highlight span classes exist for subjects that genuinely involve code or other monospaced literal text (config, shell commands, formulas). **For non-technical guides, do not use `
` blocks at all** — they would look out of place. Use tables, lists, callouts, and worked examples instead. (`code.inline` is fine everywhere for short literals.)

When you do use code, you **hand-write the highlighting** by wrapping tokens in spans. The classes are intentionally generic so they map onto any language:

|Class|Generic meaning|Typical use|
|---|---|---|
|`.c`|de-emphasized|comments|
|`.k`|keyword / control word|`if`, `function`, `class`, `return`|
|`.s`|literal value|strings, numbers|
|`.f`|callable name|function / method names|
|`.t`|type / tag / class|type names, HTML tags, class names|
|`.v`|identifier|variables|
|`.a`|annotation|attributes, decorators, directives|

Rules for code blocks:

- Keep snippets **short** (roughly 2–12 lines). They must fit on one page — `page-break-inside: avoid` is set, so an oversized block can overflow. Split long examples into several captioned blocks.
- **Escape HTML inside code**: write `<`, `>`, `&`. This is the most common rendering bug.
- Inside the dark block, a comment uses ``. Indentation is literal spaces (the block is `white-space: pre`).
- You do not need to highlight every token — highlight the ones that aid reading (keywords, strings, names). Plain text inside `
` is fine and renders in the default light color.

Example (PHP-flavored, but the pattern is language-agnostic):

```html

function greet(string $name): string {
    return "Hello, $name";   // interpolation
}

```

---

## 8. Pitfalls — read before building (these caused real bugs)

1. **Escape `<`, `>`, `&` inside `
` and ``.** Unescaped angle brackets silently swallow content or break layout. Always `< > &`.
2. **Typographic quotes in prose, straight quotes in attributes.** In body text use the target language's real quotation marks (German `„ … "`, English `" … "`). Never let a quote character inside running text collide with HTML attribute quotes. If you generate the HTML from a script, be careful that closing typographic quotes are not accidentally written as escaped ASCII quotes — that corrupts both the string and any nearby `class="…"`. The safe approach: type real `„ … "` / `" … "` glyphs in prose, and reserve `"` strictly for HTML attributes.
3. **`--footer-label` must be a quoted CSS string**, e.g. `--footer-label: "Nutrition Guide";`. An unquoted value breaks the `@page` rule.
4. **Keep code blocks and callouts short enough to fit one page.** `page-break-inside: avoid` prevents splitting but cannot shrink an oversized block; it will overflow the page. Break large blocks up.
5. **Multibyte text is fine** (umlauts, accents, CJK, symbols) — the fonts and UTF-8 charset handle it. But if you ever measure string length in a generator script, count characters, not bytes.
6. **Chapter `
` feeds the running header.** Keep it short; a very long chapter title wraps awkwardly in the 8pt header.
7. **Don't add web fonts or external assets.** The look depends on the system-font stack already specified. Adding fonts changes metrics and spacing.
8. **One accent, three shades.** Don't introduce extra brand colors. Variety comes from the callout colors (green/red/gold), which are fixed and meaningful — not decorative.
9. **Tables and code don't split** (`page-break-inside: avoid`). If a table is very long, either let it be its own short section or split it into two.

---

## 9. Build & verify

1. Write `guide.html` (single file, embedded `