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

18
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();
@@ -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();