87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# HTML deck to PPTX
|
|
|
|
This tool renders a ThothII HTML deck as one full-bleed PNG per slide and assembles
|
|
those images into a 16:9 PowerPoint file with native speaker notes and document
|
|
metadata. The HTML and notes JSON under `presentations/` are the editable sources;
|
|
the PPTX is a rendered release artifact.
|
|
|
|
Using images preserves the web typography and fine CSS details across machines. The
|
|
tradeoff is that slide text is not editable in PowerPoint. Speaker notes remain native
|
|
and editable.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 18 or newer and npm.
|
|
- Playwright's Chromium build.
|
|
- Network access while rendering the current deck, because its Fraunces and Manrope
|
|
fonts are loaded from Google Fonts. The render is therefore not fully hermetic.
|
|
|
|
Install the locked JavaScript dependencies and Chromium from the repository root:
|
|
|
|
```bash
|
|
npm ci --prefix tools/html-to-pptx
|
|
npx --prefix tools/html-to-pptx playwright install chromium
|
|
```
|
|
|
|
Dependencies are local to this tool. The scripts intentionally do not use globally
|
|
installed npm packages.
|
|
|
|
## Render slides
|
|
|
|
Use a dedicated render directory. The renderer removes stale files matching
|
|
`NN.png`, writes fresh slide images, and creates a raw `notes.json` containing the
|
|
title extracted from each slide.
|
|
|
|
```bash
|
|
npm --prefix tools/html-to-pptx run render -- \
|
|
presentations/<deck>.html <render-dir> \
|
|
--hide ".hud button,.hint"
|
|
```
|
|
|
|
The HTML deck must expose `.slide` elements activated by `#N` hash routes. Optional
|
|
rendering flags are `--scale`, `--width`, and `--height`; their defaults are `2`,
|
|
`1600`, and `900`.
|
|
|
|
## Build the PowerPoint file
|
|
|
|
Keep refined speaker notes in `presentations/<deck>.notes.json`, using the shape
|
|
`{"1": "...", "2": "..."}`. Pass that file instead of the raw titles generated
|
|
during rendering:
|
|
|
|
```bash
|
|
npm --prefix tools/html-to-pptx run build -- \
|
|
<render-dir> presentations/<deck>.pptx \
|
|
--notes presentations/<deck>.notes.json \
|
|
--title "..." --author "..." --subject "..."
|
|
```
|
|
|
|
The output uses the wide PowerPoint layout (13.333 x 7.5 inches), with one image per
|
|
slide. Edit the HTML and rebuild whenever slide content changes.
|
|
|
|
## Validation
|
|
|
|
Run the syntax checks with:
|
|
|
|
```bash
|
|
npm --prefix tools/html-to-pptx test
|
|
```
|
|
|
|
Before publishing a regenerated deck, inspect at least one PNG at full resolution and
|
|
use `python-pptx` to verify the slide count, the 12192000 x 6858000 EMU page size, and
|
|
one picture per slide. `python-pptx` is an optional, currently unpinned QA dependency;
|
|
it is not needed to render or build the deck.
|
|
|
|
The locked direct dependencies are Playwright 1.58.0 (Apache-2.0) and PptxGenJS
|
|
3.12.0 (MIT). Their transitive versions and integrity hashes are recorded in
|
|
`package-lock.json`.
|
|
|
|
### Temporary dependency exception
|
|
|
|
PptxGenJS 3.12.0 declares `image-size` 1.2.1, which npm flags for the availability-only
|
|
[GHSA-w3rx-r6r6-pgpr](https://github.com/advisories/GHSA-w3rx-r6r6-pgpr) and
|
|
[GHSA-5p2g-fcmc-qvqq](https://github.com/advisories/GHSA-5p2g-fcmc-qvqq) advisories. No patched
|
|
`image-size` release exists as of 2026-08-31, and current PptxGenJS releases retain the dependency.
|
|
The affected parser is not imported by PptxGenJS's published builder path used here; this tool also
|
|
accepts only locally generated PNG slides with explicit dimensions. Do not use it with untrusted
|
|
image inputs. Reassess this exception by 2026-11-29, or sooner when a patched dependency is released.
|