| 1 | # Authoring guide |
| 2 | |
| 3 | How to turn a user request ("make me a deck about X") into a finished |
| 4 | html-ppt deck. Follow these steps in order. |
| 5 | |
| 6 | ## 1. Understand the deck |
| 7 | |
| 8 | Before touching files, clarify: |
| 9 | |
| 10 | 1. **Audience** — engineers? designers? executives? consumers? |
| 11 | 2. **Length** — 5 min lightning? 20 min share? 45 min talk? |
| 12 | 3. **Language** — Chinese, English, bilingual? (Noto Sans SC is preloaded.) |
| 13 | 4. **Format** — on-screen live, PDF export, 小红书图文? |
| 14 | 5. **Tone** — clinical / playful / editorial / cyber? |
| 15 | |
| 16 | The audience + tone map to a theme; the length maps to slide count; the |
| 17 | format maps to runtime features (live → notes + T-cycle; PDF → page-break |
| 18 | CSS, already handled in `base.css`). |
| 19 | |
| 20 | ## 2. Pick a theme |
| 21 | |
| 22 | Use `references/themes.md`. When in doubt: |
| 23 | |
| 24 | - **Engineers** → `catppuccin-mocha` / `tokyo-night` / `dracula`. |
| 25 | - **Designers / product** → `editorial-serif` / `aurora` / `soft-pastel`. |
| 26 | - **Execs** → `minimal-white` / `arctic-cool` / `swiss-grid`. |
| 27 | - **Consumers** → `xiaohongshu-white` / `sunset-warm` / `soft-pastel`. |
| 28 | - **Cyber / CLI / infra** → `terminal-green` / `blueprint` / `gruvbox-dark`. |
| 29 | - **Pitch / bold** → `neo-brutalism` / `sharp-mono` / `bauhaus`. |
| 30 | - **Launch / product reveal** → `glassmorphism` / `aurora`. |
| 31 | |
| 32 | Wire the theme as `<link id="theme-link" href="../assets/themes/NAME.css">` |
| 33 | and list 3-5 alternatives in `data-themes` so the user can press T to audition. |
| 34 | |
| 35 | ## 3. Outline the deck |
| 36 | |
| 37 | A solid 20-minute deck is usually: |
| 38 | |
| 39 | ``` |
| 40 | cover → toc → section-divider #1 → [2-4 body pages] → |
| 41 | section-divider #2 → [2-4 body pages] → section-divider #3 → |
| 42 | [2-4 body pages] → cta → thanks |
| 43 | ``` |
| 44 | |
| 45 | Pick 1 layout per page from `references/layouts.md`. Don't repeat the same |
| 46 | layout twice in a row. |
| 47 | |
| 48 | ## 4. Scaffold the deck |
| 49 | |
| 50 | ```bash |
| 51 | ./scripts/new-deck.sh my-talk |
| 52 | ``` |
| 53 | |
| 54 | This copies `templates/deck.html` into `examples/my-talk/index.html` with |
| 55 | paths rewritten. Add/remove `<section class="slide">` blocks to match your |
| 56 | outline. |
| 57 | |
| 58 | ## 5. Author each slide |
| 59 | |
| 60 | For each outline item: |
| 61 | |
| 62 | 1. Open the matching single-page layout, e.g. `templates/single-page/kpi-grid.html`. |
| 63 | 2. Copy the `<section class="slide">…</section>` block. |
| 64 | 3. Paste into your deck. |
| 65 | 4. Replace demo data with real data. Keep the class structure intact. |
| 66 | 5. Set `data-title="..."` (used by the Overview grid). |
| 67 | 6. Add `<div class="notes">…</div>` with speaker notes. |
| 68 | |
| 69 | ## 6. Add animations sparingly |
| 70 | |
| 71 | Rules of thumb: |
| 72 | |
| 73 | - Cover/title: `rise-in` or `blur-in`. |
| 74 | - Body content: `fade-up` for the hero element, `stagger-list` for grids/lists. |
| 75 | - Stat pages: `counter-up`. |
| 76 | - Section dividers: `perspective-zoom` or `cube-rotate-3d`. |
| 77 | - Closer: `confetti-burst` on the "Thanks" text. |
| 78 | |
| 79 | Pick **one** accent animation per slide. Everything else should be calm. |
| 80 | |
| 81 | ## 7. Chinese + English decks |
| 82 | |
| 83 | - Fonts are already imported in `fonts.css` (Noto Sans SC + Noto Serif SC). |
| 84 | - Use `lang="zh-CN"` on `<html>`. |
| 85 | - For bilingual titles, stack lines: `<h1 class="h1">主标题<br><span class="dim">English subtitle</span></h1>`. |
| 86 | - Keep English subtitles in a lighter weight (300) and dim color to avoid |
| 87 | visual competition. |
| 88 | |
| 89 | ## 8. Review in-browser |
| 90 | |
| 91 | ```bash |
| 92 | open examples/my-talk/index.html |
| 93 | ``` |
| 94 | |
| 95 | Walk through every slide with ← →. Press: |
| 96 | |
| 97 | - **O** — overview grid; catch any layout clipping. |
| 98 | - **T** — cycle themes; make sure nothing looks broken in any theme. |
| 99 | - **S** — open speaker notes; verify every slide has notes. |
| 100 | |
| 101 | ## 9. Export to PNG |
| 102 | |
| 103 | ```bash |
| 104 | # single slide |
| 105 | ./scripts/render.sh examples/my-talk/index.html |
| 106 | |
| 107 | # all slides (autodetect count by looking for .slide sections) |
| 108 | ./scripts/render.sh examples/my-talk/index.html all |
| 109 | |
| 110 | # explicit slide count + output dir |
| 111 | ./scripts/render.sh examples/my-talk/index.html 12 out/my-talk-png |
| 112 | ``` |
| 113 | |
| 114 | Output is 1920×1080 by default. Change in `render.sh` if the user wants 3:4 |
| 115 | for 小红书图文 (1242×1660). |
| 116 | |
| 117 | ## 10. What to NOT do |
| 118 | |
| 119 | - Don't hand-author from a blank file. |
| 120 | - Don't use raw hex colors in slide markup. Use tokens. |
| 121 | - Don't load heavy animation frameworks. Everything should stay within the |
| 122 | CSS/JS that already ships. |
| 123 | - Don't add more than one new template file unless a genuinely new layout |
| 124 | type is needed. Prefer composition. |
| 125 | - Don't delete slides from the showcase decks. |
| 126 | - **Don't put presenter-only text on the slide.** Any descriptive text, |
| 127 | narration cues, or explanations meant for the speaker (e.g. "这一页的重点是…", |
| 128 | "Note: mention X here", small grey captions explaining the slide's purpose) |
| 129 | MUST go inside `<div class="notes">`, not as visible elements. The `.notes` |
| 130 | div is hidden (`display:none`) and only shown via the S overlay. Slides |
| 131 | should contain ONLY audience-facing content. |
| 132 | |
| 133 | ## Troubleshooting |
| 134 | |
| 135 | - **Theme doesn't switch with T**: check `data-themes` on `<body>` and |
| 136 | `data-theme-base` pointing to the themes directory relative to the HTML |
| 137 | file. |
| 138 | - **Fonts fall back**: make sure `fonts.css` is linked before the theme. |
| 139 | - **Chart.js colors wrong**: charts read CSS vars in JS; make sure they run |
| 140 | after the DOM is ready (`addEventListener('DOMContentLoaded', …)`). |
| 141 | - **PNG too small**: bump `--window-size` in `scripts/render.sh`. |
| 142 |