| 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 # base template -> examples/my-talk/ |
| 52 | ./scripts/new-deck.sh my-talk . -t pitch-deck # full-deck template, into ./my-talk/ |
| 53 | ./scripts/new-deck.sh my-talk ~/decks # anywhere, inside the skill or not |
| 54 | ``` |
| 55 | |
| 56 | This copies the chosen template into `<parent>/my-talk/index.html` and rewrites |
| 57 | every `assets/` reference to the prefix that is correct for **that** location, |
| 58 | then verifies each one resolves before reporting success. Add/remove |
| 59 | `<section class="slide">` blocks to match your outline. |
| 60 | |
| 61 | ## 5. Author each slide |
| 62 | |
| 63 | For each outline item: |
| 64 | |
| 65 | 1. Open the matching single-page layout, e.g. `templates/single-page/kpi-grid.html`. |
| 66 | 2. Copy the `<section class="slide">…</section>` block. |
| 67 | 3. Paste into your deck. |
| 68 | 4. Replace demo data with real data. Keep the class structure intact. |
| 69 | 5. Set `data-title="..."` (used by the Overview grid). |
| 70 | 6. Add `<div class="notes">…</div>` with speaker notes. |
| 71 | |
| 72 | ### Branding the deck with a logo |
| 73 | |
| 74 | Declare it **once** on `<body>`, not per slide: |
| 75 | |
| 76 | ```html |
| 77 | <body data-logo="logo.svg" data-logo-position="bottom-right" data-logo-size="40px"> |
| 78 | ``` |
| 79 | |
| 80 | Position is one of `top-left` / `top-right` / `bottom-left` / `bottom-right` |
| 81 | (default `top-right`); `data-logo-size` sets the height. Drop the logo from an |
| 82 | individual slide with `<section class="slide" data-no-logo>` — the cover usually |
| 83 | already shows the brand at full size. |
| 84 | |
| 85 | The image path is resolved relative to the deck's own HTML file, so keep the |
| 86 | file next to `index.html` (`examples/my-talk/logo.svg` → `data-logo="logo.svg"`). |
| 87 | Never hand-edit the `../` depth in asset paths — see the rule in section 10. |
| 88 | |
| 89 | If the four presets don't fit, write the element yourself inside `.deck`: |
| 90 | `<img class="deck-logo" data-pos="top-left" src="logo.svg" alt="">`. That works |
| 91 | with `runtime.js` absent entirely, since the styling lives in `base.css`. |
| 92 | |
| 93 | ## 6. Add animations sparingly |
| 94 | |
| 95 | Rules of thumb: |
| 96 | |
| 97 | - Cover/title: `rise-in` or `blur-in`. |
| 98 | - Body content: `fade-up` for the hero element, `stagger-list` for grids/lists. |
| 99 | - Stat pages: `counter-up`. |
| 100 | - Section dividers: `perspective-zoom` or `cube-rotate-3d`. |
| 101 | - Closer: `confetti-burst` on the "Thanks" text. |
| 102 | |
| 103 | Pick **one** accent animation per slide. Everything else should be calm. |
| 104 | |
| 105 | ## 7. Chinese + English decks |
| 106 | |
| 107 | - Fonts are already imported in `fonts.css` (Noto Sans SC + Noto Serif SC). |
| 108 | - Use `lang="zh-CN"` on `<html>`. |
| 109 | - For bilingual titles, stack lines: `<h1 class="h1">主标题<br><span class="dim">English subtitle</span></h1>`. |
| 110 | - Keep English subtitles in a lighter weight (300) and dim color to avoid |
| 111 | visual competition. |
| 112 | |
| 113 | ## 8. Review in-browser |
| 114 | |
| 115 | ```bash |
| 116 | open examples/my-talk/index.html |
| 117 | ``` |
| 118 | |
| 119 | Walk through every slide with ← →. Press: |
| 120 | |
| 121 | - **O** — overview grid; catch any layout clipping. |
| 122 | - **T** — cycle themes; make sure nothing looks broken in any theme. |
| 123 | - **S** — open speaker notes; verify every slide has notes. |
| 124 | |
| 125 | ## 9. Export to PNG |
| 126 | |
| 127 | ```bash |
| 128 | # single slide |
| 129 | ./scripts/render.sh examples/my-talk/index.html |
| 130 | |
| 131 | # all slides (autodetect count by looking for .slide sections) |
| 132 | ./scripts/render.sh examples/my-talk/index.html all |
| 133 | |
| 134 | # explicit slide count + output dir |
| 135 | ./scripts/render.sh examples/my-talk/index.html 12 out/my-talk-png |
| 136 | ``` |
| 137 | |
| 138 | Output is 1920×1080 by default. Change in `render.sh` if the user wants 3:4 |
| 139 | for 小红书图文 (1242×1660). |
| 140 | |
| 141 | ## 10. What to NOT do |
| 142 | |
| 143 | - Don't hand-author from a blank file. |
| 144 | - Don't use raw hex colors in slide markup. Use tokens. |
| 145 | - Don't load heavy animation frameworks. Everything should stay within the |
| 146 | CSS/JS that already ships. |
| 147 | - Don't add more than one new template file unless a genuinely new layout |
| 148 | type is needed. Prefer composition. |
| 149 | - Don't delete slides from the showcase decks. |
| 150 | - **Don't put presenter-only text on the slide.** Any descriptive text, |
| 151 | narration cues, or explanations meant for the speaker (e.g. "这一页的重点是…", |
| 152 | "Note: mention X here", small grey captions explaining the slide's purpose) |
| 153 | MUST go inside `<div class="notes">`, not as visible elements. The `.notes` |
| 154 | div is hidden (`display:none`) and only shown via the S overlay. Slides |
| 155 | should contain ONLY audience-facing content. |
| 156 | |
| 157 | ## Troubleshooting |
| 158 | |
| 159 | - **Theme doesn't switch with T**: check `data-themes` on `<body>` and |
| 160 | `data-theme-base` pointing to the themes directory relative to the HTML |
| 161 | file. |
| 162 | - **Fonts fall back**: make sure `fonts.css` is linked before the theme. |
| 163 | - **Chart.js colors wrong**: charts read CSS vars in JS; make sure they run |
| 164 | after the DOM is ready (`addEventListener('DOMContentLoaded', …)`). |
| 165 | - **PNG too small**: bump `--window-size` in `scripts/render.sh`. |
| 166 |