html-build
Generates HTML slides from slide_deck.md and design_spec.md. Applies theme (data-theme attribute), binds images from image-manifest.json, inserts speaker intro and contact slides, checks balance. Responds to "make HTML", "generate slides", "add images", "add speaker intro" (Korean: "HTML 만들어줘", "슬라이드 생성해줘", "이미지 넣어줘", "강연자 소개 추가해줘"). Stages 5-8 of the lecture workflow.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- html-build
- owner
- html-build
- scope
- co-deck
- inputs
- [ "slide-deck-draft", "design-spec" ]
- status
- active
- outputs
- [ "slide-html" ]
- version
- 1.7.0
- relates_to
- [ { "type": "follows", "skill": "pdf-export" }, { "type": "follows", "skill": "slide-layout-gate" }, { "type": "composes_with", "skill": "pdf-export" }, { "type": "composes_with", "skill": "research" }, { "type": "composes_with", "skill": "storyline" } ]
- description
- Generates HTML slides from slide_deck.md and design_spec.md. Applies theme (data-theme attribute), binds images from image-manifest.json, inserts speaker intro and contact slides, checks balance. Responds to "make HTML", "generate slides", "add images", "add speaker intro" (Korean: "HTML 만들어줘", "슬라이드 생성해줘", "이미지 넣어줘", "강연자 소개 추가해줘"). Stages 5-8 of the lecture workflow.
- last_reviewed
- 1794268800000
- prerequisites
- design
03 SKILL.md 正文
Context
Generates a single HTML file from slide_deck.md + design_spec.md, applies theme from lecture-profile.md, binds images from image-manifest.json, inserts special pages (speaker intro, contact), and checks balance. Slide data is embedded as a strict-JSON array (const slideData = [...]) inside the HTML. Strict-JSON means: all keys double-quoted, all string values double-quoted, no trailing commas, no JavaScript comments, no single-quoted strings, no template literals. Invoked at Stages 5-8, after Gate 3 (design approval).
When to Use
- PM Agent dispatches after Gate 3 (design approval)
- User says "make HTML" / "HTML 만들어줘" / "슬라이드 생성해줘"
- User says "add images" / "이미지 넣어줘"
- User wants to edit specific slides
Execution Steps
Stage 5: HTML Slide Generation
File Structure: Single HTML file (lecture_[topic]_v1.html) + assets/images/ folder (photos) + assets/diagrams/ folder (SVG/PNG diagrams).
slideData Structure: Slide data lives as a strict-JSON array embedded as const slideData = [...] inside the HTML file. All keys and string values must use double-quotes; no trailing commas, no JS comments. This enables extract_slidedata.mjs to parse via JSON.parse directly without a transform step.
Korean example — field keys stay in English; only the content values are Korean.
// Cover
{ isTitleSlide: true, section: "", title: "강연 제목", subtitle: "부제목",
meta: "날짜 | 주최", visualImage: "../assets/images/lecture-hall-professional.jpg",
backgroundImage: "../assets/images/bg-deck.jpg" }
// Speaker intro (visualImage → portrait avatar on profile slides)
{ isProfileSlide: true, section: "INTRODUCTION", title: "강연자 소개",
speakerName: "이름", speakerTitle: "직책 / 소속", speakerBio: "약력 (2-3줄)",
visualImage: "../assets/images/speaker-portrait.jpg" }
// Divider (part break)
{ isDividerSlide: true, section: "섹션명", partNum: "PART 01",
title: "파트 제목", desc: "이 파트에서 다룰 내용 한 줄 요약",
visualImage: "../assets/images/ai-transformation-abstract.jpg",
backgroundImage: "../assets/images/bg-deck.jpg" }
// Standard slide (image)
{ section: "섹션명", title: "슬라이드 제목",
bullets: ["불릿 1", "불릿 2", "불릿 3"],
visualImage: "../assets/images/data-analysis-dashboard.jpg" }
// Standard slide (text panel — structured visualDisplay)
// visualDisplay supports structured rendering via renderVisualDisplay():
// [Box Title] → .visual-heading (bold, accented)
// ✓ / → / • → .visual-item .visual-item-check (list marker)
// (default) → .visual-paragraph (normal text)
{ section: "섹션명", title: "슬라이드 제목",
bullets: ["불릿 1", "불릿 2"],
visualTitle: "핵심 포인트", visualDisplay: "[현재 상황]\n✓ 항목 1\n✓ 항목 2\n\n[개선 방향]\n→ 방향 1\n→ 방향 2" }
// Contact (last slide)
{ isContactSlide: true, section: "CLOSING", title: "감사합니다",
contactEmail: "email@example.com", contactLinkedIn: "linkedin.com/in/...",
contactPhone: "010-XXXX-XXXX" }
// Punchline (impactful closing)
{ isPunchlineSlide: true, section: "", title: "핵심 메시지" }
// Abbreviation footnotes (optional, any slide type)
// Renders as a small wrap-enabled line at the bottom-left of the slide
// (shared FootnoteBuilder — runs from initPPT, no per-theme work needed).
// Rule: define each abbreviation at its FIRST appearance per PART;
// skip divider/video slides and widely known terms (AI, company/model names).
{ section: "섹션명", title: "슬라이드 제목", bullets: ["불릿 1"],
footnotes: ["SMR: 소형모듈원전(Small Modular Reactor)", "EREV: 주행거리 연장형 전동화(Extended-Range Electric Vehicle)"] }
Use design_spec.md's CSS variables directly. Unify slide rendering through a single renderSlide(data) function. Do not hardcode color or font values.
Theme + Style injection (from lecture-profile.md → presentation.theme + presentation.style):
<html lang="ko" data-theme="pitch-enhanced" data-style="premium-dark">
<link rel="stylesheet" href="../../docs/html-themes/styles/base.css">
<link rel="stylesheet" href="../../docs/html-themes/styles/premium-dark/style.css">
Available themes: outline | pitch | pitch-enhanced | vertical | zen. Available styles: classic | minimal | visual-heavy | academic | premium-dark. Defaults: pitch-enhanced + premium-dark.
Deterministic Builder (Task 4 — pending implementation): A CLI
build-theme-deck.tswill automate CSS injection, marker replacement, and ppt-engine.js inlining. Once available, html-build will invoke the builder instead of performing these steps manually. The builder handles: theme/style resolution, package validation, INJECT marker replacement, CSS link generation, ppt-engine.js inlining, strict-JSON slideData injection. html-build remains responsible for: slide content generation, image path binding, narration/auto-advance config assembly, and renderSlide() (template-provided).
Theme capabilities:
- All 5 themes support
visualImage,visualTitle/visualDisplaytext panels, profile avatars,contactPhone,isPunchlineSlide, andfootnotes(abbreviation footnotes via the shared FootnoteBuilder). pitchandpitch-enhanceduseslide-contentgrid (left text + right visual panel) for standard slides.outline,pitch-enhanced,zen,verticaluseslide-card(content + right-panel) for standard slides.outline,pitch-enhanced,zen,verticalsupport PPT features (TOC drawer, transitions, timer, speaker notes, TTS).pitchuses its own layout (TOC drawer, no transitions).visual-heavystyle uses--slide-bg-imageCSS variable for full-bleed background images.
Narration and auto-advance config injection (from lecture-profile.md → narration + auto_advance sections):
Read the narration and auto_advance blocks from lecture-profile.md and inject two independent config objects into the initPPT() call. This bridges lecture profile settings to the runtime NarrationEngine v2.3:
// Inject before the DOMContentLoaded listener or alongside initPPT call
var narrationConfig = {
enabled: true,
autoPlay: false,
defaultLanguage: 'ko',
scriptLanguage: 'ko',
languages: ['ko']
};
var autoAdvanceConfig = {
enabled: true,
startAsAuto: false,
interval: 8
};
initPPT({ transition: 'fade', showTimer: true, showThumbnails: false,
narration: narrationConfig, autoAdvance: autoAdvanceConfig });
narration.enabled: false→ hides TTS play button, language dropdown, voice selector; disables 'P' keyboard shortcutnarration.autoPlay: true→ auto-starts TTS narration on page loadnarration.scriptLanguage→ declares what language the primaryscriptfield is written in (defaults to'ko'); read fromscript_languagein lecture-profile.md, falls back tolanguagefieldauto_advance.enabled: false→ hides auto-advance toggle button; disables 'A' keyboard shortcutauto_advance.startAsAuto: true→ starts auto-advance timer immediately on page loadauto_advance.interval→ configures the timer interval (seconds) for auto-advance slidesnarration.languages→ populates the language dropdown (only languages with scripts in slideData are clickable)- If
narrationsection is absent, setnarration.enabled: false. Ifauto_advancesection is absent, use defaults (enabled: true,startAsAuto: false,interval: 8) - Backward compatibility: if the old single
narration.autoAdvanceornarration.autoAdvanceIntervalfields are present, silently ignore them
Image paths: Photos live in the shared pool at presentations/assets/images/. Use ../assets/images/<slug>.<ext> (relative from presentations/<project>/). Slug is the path field basename from image-manifest.json. No slide-number prefix. Diagrams (SVG/PNG) live in the shared pool at presentations/assets/diagrams/. Use ../assets/diagrams/<stem>.png for diagram slides. Paths are auto-rewritten by gen-visual-images.ts when run.
Canonical rebuild order (U-20261105-007): every rebuild follows build → style patch → video inject — a rebuild silently drops video players and style patches otherwise. build-theme-deck.ts runs the video injection itself after a successful build (idempotent, video-less decks untouched); pass --download-videos to pre-fetch the deck's YouTube videos into presentations/assets/videos/yt-<id>.mp4 before injection so offline playback binds local files. Re-apply the style patch after every rebuild.
Font Parity (PDF ↔ HTML) — mandatory
A deck's typography has ONE source of truth: the font family the PDF engine
loads from presentations/assets/fonts/ (currently Pretendard-Regular/Bold.ttf,
per gen-slides-pdf.ts --font-dir default). Every HTML build MUST:
- Embed that same family via
@font-facefrom those same TTF files (CSS url relative to the stylesheet's own location) and set it FIRST in--font-family. - Keep system-font fallbacks (Noto Sans KR, Apple SD Gothic Neo) as resilience only — they are never the delivered look.
- Verify before hand-off: Playwright
document.fonts.check('400 16px <Family>')anddocument.fonts.check('700 24px <Family>')must both be true.
Any typography change (family, weights, font files) updates the PDF engine and
the HTML theme/patch in the SAME change (spec activity per ADR-0074).
Design: docs/designs/2026-11-10-font-parity-ssot-principle-design.md; gate
record: decisions/gates.yaml DG-DECK-06 (S10 sample review).
Stage 6: Image Binding
Read image-manifest.json and bind downloaded images to matching slideData entries by slide index. For slides where no image was found by the Image Curator:
- If slide has
image_role: background→ switch tovisualTitle/visualDisplaytext panel fallback - If slide has
image_role: illustrative→ omit the right panel; switch to full-text layout - Never use placeholder or generic images — always use manifest paths or text fallback
Background image binding (when lecture-profile.md → background_image.enabled is true):
- Read
background_imageconfig fromlecture-profile.md - Read the global background image path from
image-manifest.json→background_image.path - Convert to relative path:
../assets/images/<slug>.<ext> - Inject
backgroundImagefield intoslideDataentries based on scope:all→ every slide gets"backgroundImage": "../assets/images/bg-deck.jpg"divider-cover→ only slides whereisTitleSlide,isDividerSlide, orisPunchlineis trueindividual→ only slides withimage_role: "background"in the manifest
- The template's
renderSlide()readsdata.backgroundImageand sets--slide-bg-imageCSS variable (consumed byvisual-heavy/style.cssfor full-bleed backgrounds)
Stage 7: Balance Check
Self-check after generating the HTML:
- [ ] Total slide count matches the plan
- [ ] Slide counts per chapter are balanced (within ±20%)
- [ ] No slides with more than 5 bullets
- [ ] No more than 3 consecutive slides without visuals
- [ ] No overly long bullets (recommend under 40 chars/line)
If any issue, split or merge slides.
Stage 8: Special Pages
- Speaker intro: right after the cover (slide 2)
- Contact: last slide
Insert if either is missing. Populate with instructor fields from lecture-profile.md.
To open HTML locally:
bunx serve .→http://localhost:3000
Output Format
lecture_[topic]_v1.html — single self-contained HTML file with embedded const slideData (strict JSON), theme data-theme attribute, base + override CSS links, and assets/images/ (photos) + assets/diagrams/ (SVG/PNG) alongside.
PDF pipeline note:
scripts/co-deck/extract_slidedata.mjsparses the inlineconst slideData = [...]array via a bracket-depth state machine (not regex, not DOM). The slideData array MUST be strict JSON — all keys double-quoted, string values double-quoted, no trailing commas, no JS comments, no single quotes. Non-JSON syntax will break the PDF pipeline.Encoding: All output HTML files MUST be UTF-8 without BOM. Verify
<meta charset="UTF-8">is present in<head>. On Korean Windows systems, ensurechcp 65001is active before writing files to prevent CP949 corruption of Korean text content.
Builder Boundary: See
agents/html-build.md"Builder Boundary" section for the complete responsibility split between the builder and the html-build agent.
Related Skills
design— providesdesign_spec.mdCSS variables consumed by this skillimage-curator— producesimage-manifest.jsonthat maps slide indices to image pathsmeasure— next step; consumes the HTML output to extract pixel coordinatesversion— must be called before any HTML file edit
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.