Set up book project: Markdown→CSS→PDF pipeline for KDP

Adds the full authoring and build toolchain for "Das Kaleidoskop der Schlummerwelten" — all 12 story content files in Markdown, Nunjucks HTML templates, CSS print layout, and Puppeteer-based PDF generation targeting Amazon KDP (8.5×8.5 in, 0.125in bleed). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-03 15:38:07 +02:00
parent b5582a65d6
commit a8ade90ffb
26 changed files with 2219 additions and 1 deletions
@@ -0,0 +1,293 @@
+# Das Kaleidoskop der Schlummerwelten
+
+A German children's bedtime anthology — 12 independent stories with AI-generated watercolor illustrations — built for [Amazon KDP](https://kdp.amazon.com) (8.5 × 8.5 in, premium color print).
+
+The entire book is written in Markdown and styled with CSS. Running `pnpm book` produces a print-ready PDF.
+
+---
+
+## Project structure
+
+```
+kaleidoskop/
+├── content/                  # One Markdown file per story (+ front matter & finale)
+│   ├── 00-front-matter.md
+│   ├── 01-der-glaeserne-sternenwald.md
+│   ├── ...
+│   └── 13-finale-kaleidoskop.md
+│
+├── images/                   # AI-generated illustrations (300 DPI PNG/JPG)
+│   ├── cover/
+│   │   └── cover.png
+│   ├── 01/
+│   │   ├── scene-1.png       # One image per scene
+│   │   ├── scene-2.png
+│   │   ├── scene-3.png
+│   │   └── scene-4.png
+│   └── ... (02/ through 12/)
+│
+├── templates/
+│   ├── book.html             # Master Nunjucks template (title page, TOC, stories)
+│   └── story-spread.html     # Per-story layout (image page + text page per scene)
+│
+├── styles/
+│   ├── print.css             # @page rules, bleed, page dimensions
+│   ├── layout.css            # Page structure, image/text positioning
+│   └── typography.css        # Fonts, colors, story-specific theming
+│
+├── scripts/
+│   ├── build.js              # Markdown → HTML (via Nunjucks + marked)
+│   └── pdf.js                # HTML → PDF (via Puppeteer)
+│
+└── output/
+    ├── book.html             # Intermediate build artifact (gitignored)
+    └── kaleidoskop.pdf       # Final print-ready PDF
+```
+
+---
+
+## Prerequisites
+
+- **Node.js** ≥ 18
+- **pnpm** — `npm install -g pnpm`
+- **Chromium** (ARM64 / WSL2 only — Puppeteer's bundled Chrome is x86-64)
+  ```bash
+  sudo apt-get install -y chromium
+  ```
+
+---
+
+## Setup
+
+```bash
+pnpm install
+```
+
+---
+
+## Build commands
+
+| Command | What it does |
+|---|---|
+| `pnpm build` | Converts Markdown → `output/book.html` |
+| `pnpm pdf` | Renders `output/book.html` → `output/kaleidoskop.pdf` |
+| `pnpm book` | Both steps in sequence |
+| `pnpm watch` | Auto-rebuilds HTML on file changes (no PDF) |
+
+---
+
+## Writing a story
+
+Each story lives in `content/XX-story-name.md`. The file has two parts:
+
+### 1. Frontmatter (YAML)
+
+```yaml
+---
+number: 1
+title: "Der gläserne Sternenwald"
+character: Leo
+palette:
+  primary: "#1a3a6b"      # Main accent color (used for headings, borders)
+  secondary: "#c0c0c0"    # Secondary accent (ornaments, dividers)
+  text: "#1a3a6b"         # Body text color
+  background: "#f0f4ff"   # Text page background color
+scenes:
+  - image: images/01/scene-1.png
+    alt: "Das Glühwürmchen am Fenster"
+  - image: images/01/scene-2.png
+    alt: "Der Mondlichtpfad"
+  - image: images/01/scene-3.png
+    alt: "Der gläserne Sternenwald"
+  - image: images/01/scene-4.png
+    alt: "Das schlafende Kind"
+---
+```
+
+### 2. Body text
+
+Four scene paragraphs separated by `---`. They map to the four scenes in order:
+
+```markdown
+Leo lag in seinem gemütlichen Bett...   ← Scene 1 text
+
+---
+
+Leo schlüpfte in seine Hausschuhe...   ← Scene 2 text
+
+---
+
+Am Ende des Pfades blieben sie stehen... ← Scene 3 text
+
+---
+
+„Es ist Zeit zum Träumen", raunte die Eule. ← Scene 4 text
+```
+
+---
+
+## Adding illustrations
+
+Place AI-generated images at the paths listed in the story's frontmatter:
+
+```
+images/01/scene-1.png
+images/01/scene-2.png
+images/01/scene-3.png
+images/01/scene-4.png
+```
+
+**Before you have images:** The build automatically shows a colored placeholder box (using the story's primary palette color) so you can work on text and layout without waiting for all 48 illustrations.
+
+**Image requirements for KDP:**
+- **Resolution:** 300 DPI minimum — upscale AI output with [Upscayl](https://upscayl.org) (free) or Topaz Gigapixel AI
+- **Dimensions:** At least 2550 × 2550 px (= 8.5 in × 300 DPI)
+- **Format:** PNG or JPG
+- **Color space:** RGB (KDP accepts RGB — no CMYK conversion needed)
+
+> See `DOSSIER.md` for the complete AI image prompts for all 48 scenes.
+
+---
+
+## Page layout
+
+Each scene produces two facing pages:
+
+```
+┌──────────────┬──────────────┐
+│              │              │
+│  Full-bleed  │  Story text  │
+│ illustration │  (right pg)  │
+│  (left pg)   │              │
+└──────────────┴──────────────┘
+```
+
+- 4 scenes × 2 pages = **8 pages per story**
+- 12 stories = **96 interior pages**
+- Plus title page, copyright, table of contents, and finale = ~**101 pages total**
+
+The story title appears at the top of the first text page. The story-specific color palette is applied via CSS custom properties injected from the frontmatter.
+
+---
+
+## Customizing the design
+
+### Changing fonts
+
+Add a `@font-face` declaration to `styles/typography.css` and update the `font-family` on `body`. Puppeteer will embed the font in the PDF automatically.
+
+```css
+@font-face {
+  font-family: 'MyFont';
+  src: url('../fonts/MyFont-Regular.woff2') format('woff2');
+}
+
+body {
+  font-family: 'MyFont', Georgia, serif;
+}
+```
+
+### Changing per-story colors
+
+Edit the `palette` block in the story's frontmatter. Available properties:
+
+| Key | Applied to |
+|---|---|
+| `primary` | Story title heading, text color, accent borders |
+| `secondary` | Ornament `✦`, dividers |
+| `text` | Scene body text |
+| `background` | Text page background |
+
+### Dark text pages (e.g. story 9)
+
+Story 9 (*Das Ballett der Nachtfalter*) uses a near-black background. Its text page is overridden in `styles/typography.css`:
+
+```css
+[data-story="9"].page--text { background: #0a0a2a; }
+[data-story="9"] .scene-text { color: #ffffff; }
+```
+
+Add similar overrides for any story that needs special treatment.
+
+### Page size / bleed
+
+Defined in `styles/print.css`:
+
+```css
+@page {
+  size: 8.75in 8.75in;   /* 8.5in trim + 0.125in bleed on each side */
+  margin: 0;
+}
+
+.page {
+  width: 8.75in;
+  height: 8.75in;
+}
+```
+
+To change trim size, update both values here and the matching `width`/`height` in `scripts/pdf.js`.
+
+---
+
+## KDP submission checklist
+
+1. **Run `pnpm book`** to generate `output/kaleidoskop.pdf`
+2. **Verify page count** is correct in your PDF viewer
+3. **Check fonts are embedded:**
+   ```bash
+   pdfinfo output/kaleidoskop.pdf | grep -i font
+   # or: pdffonts output/kaleidoskop.pdf
+   ```
+4. **Upload to KDP:**
+   - Log in → Your Books → Create → Paperback
+   - Trim size: **8.5 × 8.5 inches**
+   - Interior: **Premium Color**, 100 gsm
+   - Bleed: **Yes (with bleed)**
+   - Upload `output/kaleidoskop.pdf` as the interior file
+5. **Use the KDP online previewer** to check layout before ordering a proof
+6. **Order a proof copy** before publishing — real print color may differ from screen
+
+---
+
+## AI image prompts
+
+All prompts are in [`DOSSIER.md`](./DOSSIER.md) under each story's `KI-Bild-Prompts` section. The global style guide (paste at the start of every prompt):
+
+```
+whimsical storybook illustration, dreamy watercolor style, soft cinematic lighting,
+magical atmosphere, high resolution, 300 DPI
+```
+
+Recommended tools: **Midjourney**, **DALL-E 3**, **Ideogram**, or **Adobe Firefly**.
+
+---
+
+## Git & large files
+
+Images are tracked in git as binary files. If the repo grows large (each 300 DPI PNG can be 5–20 MB × 48 scenes), consider enabling [Git LFS](https://git-lfs.com):
+
+```bash
+git lfs install
+git lfs track "images/**/*.png" "images/**/*.jpg"
+git add .gitattributes
+```
+
+---
+
+## Troubleshooting
+
+**`pnpm pdf` fails with "Syntax error: redirection unexpected"**
+Puppeteer's bundled Chrome is x86-64 but your system is ARM64. Install system Chromium:
+```bash
+sudo apt-get install -y chromium
+```
+The script auto-detects `/usr/bin/chromium` and uses it instead.
+
+**Images are not showing in the PDF**
+Check that the image path in the story's frontmatter matches the actual file location exactly (case-sensitive).
+
+**Text is cut off on a page**
+Increase the font size or reduce padding in `styles/typography.css` and `styles/layout.css`. You can also split a long scene text into shorter paragraphs.
+
+**Colors look different in print vs. screen**
+KDP calibrates for print. Order a proof copy to see the real result before publishing. Dark tones (story 8 — bronze/chocolate) benefit from premium color paper (100 gsm).