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

56
templates/Format/Guide.md
View File

@@ -1,4 +1,3 @@
```
# 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, …).
@@ -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).
- The HTML converts to PDF with **WeasyPrint**. The canonical build command is:
```
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.
- 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:
- **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.
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.
- 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.
- 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.
@@ -294,7 +291,7 @@ html, body {
CHAPTER
============================================================ */
.chapter {
page-break-before: always;
margin-top: 8mm; /* chapters flow continuously; no forced page break */
}
.chapter-head {
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).
|Variable|What it is|Example (PHP)|
| Variable | What it is | Example (PHP) |
|---|---|---|
|`--accent`|main accent (kickers, links, code-inline, table tint sources)|`#777BB4`|
|`--accent-dark`|headings, table header background|`#4F5B93`|
|`--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"`|
| `--accent` | main accent (kickers, links, code-inline, table tint sources) | `#777BB4` |
| `--accent-dark` | headings, table header background | `#4F5B93` |
| `--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"` |
### 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
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
<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):
|Flavor|Color|Use for|
| 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|
| `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 `&#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:
|Class|Generic meaning|Typical use|
| 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|
| `.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:
@@ -728,17 +725,15 @@ Example (PHP-flavored, but the pattern is language-agnostic):
1. Write `guide.html` (single file, embedded `<style>`, UTF-8).
2. Convert:
```
weasyprint guide.html guide.pdf
```
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 # 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 1 -l 1 guide.pdf cover # cover
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.
4. If something is off, fix the HTML and rebuild. Two or three iterations is normal.
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
- [ ] Built with WeasyPrint and **visually verified** by rendering pages
- [ ] Both HTML and PDF delivered
```

2
templates/Referenz/Guide.md
View File

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