fredliu168/html_to_editable_ppt_skill/html-to-editable-ppt-skill

HTML to Editable PPT

Use this skill to convert 16:9 HTML slide decks into .pptx.

It supports two modes:

• editable: create a background screenshot without DOM text or <img> elements, then restore independent PPT pictures and editable text boxes at their measured DOM positions.
• screenshot: create a visually faithful PPT where each slide is one full-slide screenshot image. Use this only when the user does not need editable text.

Core Workflow

1. Identify the HTML source:

• Local file: /abs/path/index.html
• URL: http://..., https://..., or file://...

1. Decide mode:

• If the user says “字要可编辑”, “editable text”, “可编辑版”, use editable.
• If the user only asks “转成 PPT” and says nothing about editing, prefer screenshot for maximum fidelity, but mention text will not be editable.

1. Run scripts/html_to_ppt.mjs.
2. Validate:

• PPTX opens or imports.
• Slide count matches HTML.
• In editable mode, slide XML contains <a:t> text runs.
• Render at least a few pages back to PNG and inspect for missing text, duplicated text, or bad wrapping.

Quick Commands

Editable text version:

node /Users/fred/.codex/skills/html-to-editable-ppt/scripts/html_to_ppt.mjs \
  --html /absolute/path/index.html \
  --out /absolute/path/output-editable.pptx \
  --mode editable \
  --slides 10 \
  --workdir /absolute/path/html-to-ppt-work

Screenshot-only version:

node /Users/fred/.codex/skills/html-to-editable-ppt/scripts/html_to_ppt.mjs \
  --html /absolute/path/index.html \
  --out /absolute/path/output-screenshot.pptx \
  --mode screenshot \
  --slides 10

If the script reports missing dependencies, install them in the chosen workdir:

cd /absolute/path/html-to-ppt-work
npm init -y
npm install playwright-core pptxgenjs

Important Implementation Rules

• In editable mode, always hide HTML text before taking the background screenshot. Also hide <img> elements without changing layout before capturing the background. Restore them as independent PPT pictures using stage-relative coordinates and dimensions; never leave duplicate images baked into the background. <picture> sources are resolved by the browser.
• If the deck ignores ?slide=N, use its Home/ArrowRight navigation and confirm the target slide is visible before extraction. Exclude navigation outside the stage from screenshots.
• Preserve the HTML font family by default; font flags override it. Convert font sizes and letter spacing with the same stage scale as the measured coordinates. Keep text fragments separated around inline elements to avoid overlapping emphasis.
• Text extraction must be scoped to the current slide/stage. Do not use global selectors that accidentally extract slide 1 text for every slide.
• Prefer per-line text boxes instead of one large text box for multi-line headings. PowerPoint and browser font metrics differ; per-line boxes reduce reflow.
• Extract visible images before hiding them. Wait for fonts and images to load; fail on broken visible images instead of silently omitting them. Capture isolated images with transparency to preserve object-fit, rounded corners and clipping.
• Preserve brand logos as image content. Do not recreate protected logos as text or shapes.
• If the HTML has a custom slide/stage structure, pass --stage-selector, using N as the slide number placeholder.

Example custom stage selector:

--stage-selector '.page[data-index="N"] .canvas'

Validation Checklist

After export, check:

• slides == expected count
• editable mode has nonzero text runs in each slide
• text is not duplicated or ghosted
• text on non-cover slides is not copied from slide 1
• page numbers and logos are in the right place
• no visible DOM text or extracted images remain baked into the background screenshot
• each visible <img> is an independent <p:pic> at the correct position and size; moving it reveals a clean background

For a quick XML text-run check:

python3 - <<'PY'
from zipfile import ZipFile
from pathlib import Path
import re
pptx = Path('/absolute/path/output-editable.pptx')
with ZipFile(pptx) as z:
    slides = sorted([n for n in z.namelist() if n.startswith('ppt/slides/slide') and n.endswith('.xml')])
    for i, n in enumerate(slides, 1):
        xml = z.read(n)
        texts = re.findall(rb'<a:t>(.*?)</a:t>', xml)
        print(i, len(texts), [t.decode('utf-8', 'ignore')[:24] for t in texts[:4]])
PY

Known Limits

• Image extraction currently covers <img> (including <picture>), not CSS background images, inline SVG or canvas; those remain in the background.
• Pictures are browser-rendered PNGs, movable/resizable as independent PPT objects; their pixels are not editable shapes.
• Layer order is background, pictures in DOM order, then text. Complex z-index overlaps, foreground decorations and blend modes may differ; inspect these slides visually. Image shadows extending beyond the image bounding box are not preserved.

• Editable text fidelity depends on installed fonts. If the target machine lacks the HTML fonts, PowerPoint will substitute.
• Complex SVG text or canvas-rendered text may not be extractable as editable PPT text.
• HTML animations are captured as static screenshots at load time.
• For remote sites that require authentication, use the browser/chrome skills to make a local HTML snapshot first.