marek/guides
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
team3
2026-05-30 23:24:48 +02:00
parent 03a388864c
commit 7507bed55c
2 changed files with 36 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
templates/Format/Guide.md
View File

@@ -1,4 +1,3 @@
```
# Guide Style System — Authoring & Build Specification # 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, …). 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, …).
@@ -18,11 +17,9 @@ Follow this spec exactly. The visual identity depends on small details (spacing,
- **One HTML file**, self-contained: a single `<style>` block in `<head>`, no external CSS, no external JS, no web fonts. Fonts are system fonts only (see §3). - **One HTML file**, self-contained: a single `<style>` block in `<head>`, no external CSS, no external JS, no web fonts. Fonts are system fonts only (see §3).
- The HTML converts to PDF with **WeasyPrint**. The canonical build command is: - The HTML converts to PDF with **WeasyPrint**. The canonical build command is:
```
``` weasyprint guide.html guide.pdf
weasyprint guide.html guide.pdf ```
```
- Page size is **A4**. All page furniture (page numbers, running header, footer label) is produced by CSS `@page` rules — you never write headers/footers into the body. - Page size is **A4**. All page furniture (page numbers, running header, footer label) is produced by CSS `@page` rules — you never write headers/footers into the body.
- The body is laid out as: **Cover → Table of Contents → Part 1 divider → its chapters → Part 2 divider → its chapters → …** - The body is laid out as: **Cover → Table of Contents → Part 1 divider → its chapters → Part 2 divider → its chapters → …**
@@ -35,7 +32,7 @@ If WeasyPrint is unavailable, the HTML must still be a valid, good-looking stand
A guide is a short book. The structure is always the same three levels: A guide is a short book. The structure is always the same three levels:
- **Part** — a major thematic section (e.g. "Fundamentals", "Advanced", "Pitfalls"). Each part gets a full-page **divider**. A guide typically has **3–8 parts**. - **Part** — a major thematic section (e.g. "Fundamentals", "Advanced", "Pitfalls"). Each part gets a full-page **divider**. A guide typically has **3–8 parts**.
- **Chapter** — one focused topic, starts on a new page. **3–10 chapters per part**. Each chapter is numbered sequentially across the whole guide (Chapter 1, 2, 3 … regardless of part). - **Chapter** — one focused topic. Chapters flow continuously down the page (they do not force a page break); each is separated from the previous by spacing and its own heading block. **3–10 chapters per part**. Each chapter is numbered sequentially across the whole guide (Chapter 1, 2, 3 … regardless of part).
- **Section** (`<h2>`) and **sub-section** (`<h3>`) — structure inside a chapter. - **Section** (`<h2>`) and **sub-section** (`<h3>`) — structure inside a chapter.
Length scales with ambition: a compact guide is ~15–30 pages, a comprehensive one 80–250 pages. Decide based on the request and tell the reader the scope on the cover. Length scales with ambition: a compact guide is ~15–30 pages, a comprehensive one 80–250 pages. Decide based on the request and tell the reader the scope on the cover.
@@ -44,7 +41,7 @@ Length scales with ambition: a compact guide is ~15–30 pages, a comprehensive
- Write in the **reader's language** (German request → German guide). This spec is in English, but that does not constrain the output language. - Write in the **reader's language** (German request → German guide). This spec is in English, but that does not constrain the output language.
- Open each chapter with a one- or two-sentence **lead** (`.lead`) that frames why the topic matters. - 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. - 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. - 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. - Use **callouts** to highlight tips, warnings, side-notes, and deeper digressions — not more than one or two per chapter.
- Keep prose tight. This is a reference people skim and return to, not an essay. - Keep prose tight. This is a reference people skim and return to, not an essay.
@@ -294,7 +291,7 @@ html, body {
CHAPTER CHAPTER
============================================================ */ ============================================================ */
.chapter { .chapter {
page-break-before: always; margin-top: 8mm; /* chapters flow continuously; no forced page break */
} }
.chapter-head { .chapter-head {
string-set: chaptertitle content(); string-set: chaptertitle content();
@@ -463,12 +460,12 @@ td code, th code {
Change **four** values per guide; leave the rest unless you have a reason. The accent color is the entire brand: pick one that fits the topic, then derive a darker and darkest shade from it (roughly: accent at ~55% lightness, accent-dark ~40%, accent-darker ~28%, all at similar hue). Change **four** values per guide; leave the rest unless you have a reason. The accent color is the entire brand: pick one that fits the topic, then derive a darker and darkest shade from it (roughly: accent at ~55% lightness, accent-dark ~40%, accent-darker ~28%, all at similar hue).
|Variable|What it is|Example (PHP)| | Variable | What it is | Example (PHP) |
|---|---|---| |---|---|---|
|`--accent`|main accent (kickers, links, code-inline, table tint sources)|`#777BB4`| | `--accent` | main accent (kickers, links, code-inline, table tint sources) | `#777BB4` |
|`--accent-dark`|headings, table header background|`#4F5B93`| | `--accent-dark` | headings, table header background | `#4F5B93` |
|`--accent-darker`|cover gradient end + part titles|`#2C3E66`| | `--accent-darker` | cover gradient end + part titles | `#2C3E66` |
|`--footer-label`|short title shown bottom-right every page; **must be a quoted CSS string**|`"PHP Komplett-Guide"`| | `--footer-label` | short title shown bottom-right every page; **must be a quoted CSS string** | `"PHP Komplett-Guide"` |
### Recommended accent palettes (free to ignore or replace) ### Recommended accent palettes (free to ignore or replace)
@@ -601,7 +598,7 @@ One full page that introduces a part. The chapter list mirrors the TOC entries f
### 6.4 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 `<h1>` reasonably short so it fits on one header line. 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 `<h1>` reasonably short so it fits on one header line.
```html ```html
<section class="chapter"> <section class="chapter">
@@ -652,12 +649,12 @@ Four flavors. Each has a short uppercase label as the **first `<b>`** inside `.c
Meaning of each flavor (topic-independent): Meaning of each flavor (topic-independent):
|Flavor|Color|Use for| | Flavor | Color | Use for |
|---|---|---| |---|---|---|
|`tip`|green, ✓|best practice, a recommendation, a shortcut| | `tip` | green, ✓ | best practice, a recommendation, a shortcut |
|`warn`|red, !|a common mistake, risk, or thing to avoid| | `warn` | red, ! | a common mistake, risk, or thing to avoid |
|`note`|accent, i|a neutral aside, clarification, context| | `note` | accent, i | a neutral aside, clarification, context |
|`deep`|gold, ◆|optional depth: history, edge case, advanced detail| | `deep` | gold, ◆ | optional depth: history, edge case, advanced detail |
Standard icon entities: tip `&#10003;` (✓), warn `!`, note `i`, deep `&#9670;` (◆). You may substitute a more fitting single glyph, but keep it one character. Standard icon entities: tip `&#10003;` (✓), warn `!`, note `i`, deep `&#9670;` (◆). You may substitute a more fitting single glyph, but keep it one character.
@@ -683,15 +680,15 @@ The dark `<pre>` block and the highlight span classes exist for subjects that ge
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: 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| | Class | Generic meaning | Typical use |
|---|---|---| |---|---|---|
|`.c`|de-emphasized|comments| | `.c` | de-emphasized | comments |
|`.k`|keyword / control word|`if`, `function`, `class`, `return`| | `.k` | keyword / control word | `if`, `function`, `class`, `return` |
|`.s`|literal value|strings, numbers| | `.s` | literal value | strings, numbers |
|`.f`|callable name|function / method names| | `.f` | callable name | function / method names |
|`.t`|type / tag / class|type names, HTML tags, class names| | `.t` | type / tag / class | type names, HTML tags, class names |
|`.v`|identifier|variables| | `.v` | identifier | variables |
|`.a`|annotation|attributes, decorators, directives| | `.a` | annotation | attributes, decorators, directives |
Rules for code blocks: Rules for code blocks:
@@ -728,18 +725,16 @@ Example (PHP-flavored, but the pattern is language-agnostic):
1. Write `guide.html` (single file, embedded `<style>`, UTF-8). 1. Write `guide.html` (single file, embedded `<style>`, UTF-8).
2. Convert: 2. Convert:
```
``` weasyprint guide.html guide.pdf
weasyprint guide.html guide.pdf ```
```
3. **Verify visually.** Render a few pages to images and look at them — do not trust the HTML alone: 3. **Verify visually.** Render a few pages to images and look at them — do not trust the HTML alone:
```
``` pdftoppm -png -r 80 -f 1 -l 1 guide.pdf cover # cover
pdftoppm -png -r 80 -f 1 -l 1 guide.pdf cover # coverpdftoppm -png -r 80 -f 2 -l 2 guide.pdf toc # contentspdftoppm -png -r 80 -f 5 -l 6 guide.pdf body # a content spread pdftoppm -png -r 80 -f 2 -l 2 guide.pdf toc # contents
``` pdftoppm -png -r 80 -f 5 -l 6 guide.pdf body # a content spread
```
Check: cover gradient and title; TOC alignment; a part divider; at least one callout; at least one table; (if technical) one code block with highlighting; the running header showing the chapter title; no block overflowing a page edge; quotes and special characters rendering as glyphs, not boxes. Check: cover gradient and title; TOC alignment; a part divider; at least one callout; at least one table; (if technical) one code block with highlighting; the running header showing the chapter title; no block overflowing a page edge; quotes and special characters rendering as glyphs, not boxes.
4. If something is off, fix the HTML and rebuild. Two or three iterations is normal. 4. If something is off, fix the HTML and rebuild. Two or three iterations is normal.
5. Deliver **both** `guide.html` and `guide.pdf`. 5. Deliver **both** `guide.html` and `guide.pdf`.
@@ -757,4 +752,3 @@ Example (PHP-flavored, but the pattern is language-agnostic):
- [ ] Prose in the reader's language; terms explained on first use - [ ] Prose in the reader's language; terms explained on first use
- [ ] Built with WeasyPrint and **visually verified** by rendering pages - [ ] Built with WeasyPrint and **visually verified** by rendering pages
- [ ] Both HTML and PDF delivered - [ ] Both HTML and PDF delivered
```

2
templates/Referenz/Guide.md
View File

@@ -240,7 +240,7 @@ html, body {
KAPITEL KAPITEL
============================================================ */ ============================================================ */
.chapter { .chapter {
page-break-before: always; margin-top: 8mm;
} }
.chapter-head { .chapter-head {
string-set: chaptertitle content(); string-set: chaptertitle content();