LearnDeck

Quick Start

This skill has two main commands.

1. Generate PPT

Use this when the user asks to create a new PPT/PPTX from a topic, outline, notes, or source material.

1. Create a slide plan JSON using the shape in examples/slides.example.json.
2. Run:

node /path/to/learn-deck/scripts/generate_ppt.js \
  --slides /path/to/slides.json \
  --out-dir /path/to/output \
  --name deck-name \
  --style clean \
  --no-preview

This command first writes <out-dir>/<name>.html, then calls the HTML-to-PPT converter.

2. HTML to PPT

Use this when the user already has a local HTML file or URL:

node /path/to/learn-deck/scripts/html_to_ppt.js \
  --input /path/to/source.html \
  --out-dir /path/to/output \
  --name deck-name

If Codex workspace dependencies are available, prefer the bundled runtime:

NODE_PATH="$NODE_MODULES:/Users/$USER/node_modules" "$NODE_BIN" \
  /path/to/learn-deck/scripts/generate_ppt.js \
  --slides /path/to/slides.json \
  --out-dir /path/to/output \
  --name deck-name \
  --style clean \
  --no-preview

or:

NODE_PATH="$NODE_MODULES:/Users/$USER/node_modules" "$NODE_BIN" \
  /path/to/learn-deck/scripts/html_to_ppt.js \
  --input /path/to/source.html \
  --out-dir /path/to/output \
  --name deck-name

When running in Codex Desktop, call load_workspace_dependencies first and set:

• NODE_BIN to the returned Node.js executable.
• NODE_MODULES to the returned Node.js packages directory.

Workflow

Generate PPT

1. Ask one short style question when the user has not specified a style and the request is not urgent. Offer choices such as clean, academic, warm, bold, or dark; if the user says they do not care, choose based on audience and topic.
2. Turn the user's topic/content into a concise slides.json plan. Include "style": "<chosen-style>" in the plan or pass --style.
3. Keep each slide focused; split long content into more slides rather than crowding one slide.
4. Use layout values cover, content, steps, compare, or summary when useful.
5. Run scripts/generate_ppt.js; it writes HTML and then runs the converter. Use --no-preview by default for direct delivery.
6. Do not run extra validation by default. Directly report the generated .html and .pptx paths to the user/customer.

Revision Loop

When the user/customer asks for adjustments after delivery:

1. Edit the original generated HTML file rather than starting over.
2. Run scripts/html_to_ppt.js on that same HTML file with the same --name/output directory.
3. Return the regenerated PPTX path. Only validate or preview when the user explicitly asks or a conversion error occurs.

HTML to PPT

1. Load the HTML in Chromium/Chrome through Playwright.
2. Wait for network idle and document.fonts.ready.
3. Detect slides with .slide by default; pass --slide-selector for another selector.
4. Read every visible DOM element's bounding box, computed styles, text runs, pseudo bullets, and SVG children relative to its slide.
5. Save each inline SVG to <output>/<base>-assets/svg/ and a PNG preview to <output>/<base>-assets/png/.
6. Create a PPTX with:
   • Editable text boxes for headings, paragraphs, spans, list items, and labels.
   • Editable rectangle/rounded-rectangle/ellipse shapes for backgrounds, pills, cards, borders, and bullets.
   • Separate image objects for extracted SVG icons, using PNG in the PPTX for compatibility while preserving source SVGs on disk.
   • Native OOXML linear gradients where possible.
7. Deliver the generated PPTX path directly. Do not run extra validation by default; validate only when explicitly requested or when troubleshooting a failed conversion.

Script Options

node scripts/generate_ppt.js --help
node scripts/html_to_ppt.js --help-converter

Important HTML-to-PPT options:

• --input <file-or-url>: Required. Local HTML file or HTTP(S) URL.
• --out-dir <dir>: Required. Output directory.
• --name <base>: Output basename. Defaults to input filename.
• --style <name>: For generate_ppt.js, choose clean, academic, warm, bold, or dark.
• --slide-selector <css>: Defaults to .slide.
• --chrome <path>: Use a specific Chrome/Edge/Chromium executable.
• --ppt-width <inches> and --ppt-height <inches>: Defaults to 13.333 x 7.5.
• --keep-raw: Keep the intermediate unpatched PPTX.
• --no-preview: Skip LibreOffice PDF/PNG preview generation.

Bundled Showcase Templates

LearnDeck includes two editable four-slide showcase templates:

• templates/learn-deck-showcase-zh.pptx
• templates/learn-deck-showcase-en.pptx

Use them as visual references when the user asks for the LearnDeck showcase style, or clone and revise them when a four-slide knowledge-to-PPT overview matches the request.

Notes

• generate_ppt.js expects an agent-authored slide plan JSON; it is intentionally deterministic and does not call an LLM by itself.
• This skill prioritizes editable separated elements over screenshot-perfect fidelity.
• Browser coordinates are authoritative. Avoid hand-calculating flex/grid positions when the script can read them.
• PowerPoint and LibreOffice may lay out CJK fonts slightly differently from Chrome. Use installed system fonts such as PingFang SC or pass --font-face.
• Complex CSS effects are approximated: radial backgrounds become translucent ellipses, box shadows become approximate PowerPoint shadows, and CSS filters are ignored.
• If SVG support in PowerPoint is important, keep the saved SVG assets and replace the generated PNG icon objects manually or adapt the script. PptxGenJS needs PNG previews for SVG in Node, so PNG is the compatibility default.