pptgenerator-cli

Slide outline (Markdown / JSON) → HTML preview → PPTX, Manus-style.

pptgenerator-cli is a Node.js + TypeScript pipeline that takes a slide outline and produces:

1. a self-contained HTML preview styled with Tailwind (via CDN) and Iconify icons — the same visual you ship to PowerPoint;
2. a real .pptx file built from that HTML by screenshotting each slide and embedding it full-bleed (the image strategy). A future structured strategy will produce editable PPT shapes.

The whole flow is designed around a single in-memory contract — the SlideDeck IR — so adding a new input format = new parser, and adding a new output format = new renderer.

deck.md / deck.json ─▶ parsers/ ─▶ SlideDeck IR ─┬─▶ renderers/html/    ─▶ deck.preview.html
                                                 └─▶ renderers/pptx/    ─▶ deck.pptx
                                                       (image strategy)

Install

pnpm install
pnpm playwright:install   # downloads chromium for the image strategy

CLI

# Render the HTML preview (open it directly in any browser)
pnpm render-html examples/deck.md -o out/deck.html

# Build a .pptx (default: image strategy)
pnpm build-pptx examples/deck.md -o out/deck.pptx

# Future: editable shapes (currently throws "not implemented yet")
pnpm build-pptx examples/deck.md -o out/deck.pptx --strategy structured

Library

import { loadDeck, renderHtml, buildPptx } from "pptgenerator-cli";

const deck = loadDeck("examples/deck.md"); // auto-detects md vs json
const html = renderHtml(deck); // string
await buildPptx(deck, { outputPath: "deck.pptx" }); // image strategy by default

Markdown convention

Slides are separated by a blank-line --- thematic break. Inside a slide a blank-line ::: line splits a two-column layout.

---
title: My Deck
author: Yuki
theme: default
---

# Title slide

## Optional subtitle

---

## Section divider

---

## A content slide

- :icon[lucide:rocket] Bullets can carry an inline icon
- Plain bullet
- More text

---

## Two-column slide

- left bullet 1
- left bullet 2

:::

- right bullet 1
- right bullet 2

Theme names accepted by frontmatter: default, dark, minimal.

JSON shape

examples/deck.json mirrors the IR exactly. The IR is validated with zod (src/ir/schema.ts) and the TypeScript types live in src/ir/types.ts.

Icons (Iconify CDN)

We never bundle SVGs. The HTML renderer emits

<img src="https://api.iconify.design/lucide/rocket.svg?width=48" />

so any of Iconify's 200,000+ icons can be referenced via prefix:slug (lucide:rocket, mdi:account, tabler:wand, …). The image strategy pre-renders the HTML in headless chromium, so the icons end up baked into the .pptx pixels — your audience never needs internet access.

Project layout

src/
  cli.ts                       # `pptgenerator-cli` binary
  index.ts                     # library exports
  ir/{types,schema}.ts         # SlideDeck IR + zod validator
  parsers/{markdown,json,index}.ts
  renderers/
    html/{render,template,icons}.ts
    pptx/{render,strategy,image-strategy,structured-strategy}.ts
examples/{deck.md,deck.json}
tests/                         # vitest specs

Scripts

script	purpose
pnpm dev <args>	run the CLI from source via tsx
pnpm render-html	shorthand for dev render-html
pnpm build-pptx	shorthand for dev build-pptx
pnpm build	bundle to dist/ with tsup
pnpm typecheck	tsc --noEmit
pnpm test	vitest — Layers A, B, B+ unit, D (cheap, default-on)
pnpm test:integration	sets PPT_INTEGRATION=1 — adds Layer B+ PPTX media audit
pnpm test:visual	sets PPT_VISUAL=1 — Layer C visual regression (run inside Docker)
pnpm test:watch	vitest in watch mode
pnpm lint	ESLint over src/ and tests/
pnpm format[:check]	Prettier write / check
pnpm playwright:install	download chromium (one-off, required for image strategy)

Evaluation harness

Because the pipeline is HTML → PNG → PPTX, regressions can hide at multiple layers. tests/ is organized as a layered harness so cheap checks run on every push and expensive ones only when explicitly invoked.

layer	what it guards	gate
A	IR shape after parsing (tests/snapshots/parsers.snap)	always on
B	HTML structure / Tailwind class output	always on
B+	PPTX media + structural audit (unzip + magic bytes)	unit always; chromium leg PPT_INTEGRATION=1
C	Pixel-level visual regression with pixelmatch	PPT_VISUAL=1, Docker only
D	--evaluation-mode swaps CDNs for vendored offline assets	always on (static checks)

--evaluation-mode

Both subcommands accept --evaluation-mode. When set, the renderer rewrites Tailwind + Iconify CDN refs to file:// URLs under vendored/:

pnpm build-pptx examples/deck.md -o out/deck.pptx --evaluation-mode

Use it for air-gapped builds, deterministic CI runs, or to make Layer C visual baselines reproducible across machines.

Updating Layer C baselines (Docker)

Visual baselines depend on the exact chromium build, system fonts, and the Linux text-rendering stack — so they are produced and compared inside the shipped Docker image only:

docker build -t pptgenerator-cli:dev .
docker run --rm -e PPT_VISUAL_UPDATE=1 \
    -v "$PWD":/work -w /app pptgenerator-cli:dev \
    /app/node_modules/.bin/vitest run tests/visual

Commit the regenerated PNGs under tests/visual/__baseline__/.

Distribution

Three publishing tracks ship with v* tags:

1. npm (pptgenerator-cli) — npx pptgenerator-cli build-pptx ... (release.yml).
2. Docker (GHCR ghcr.io/chibayuki347/pptgenerator-cli) — the canonical environment for Layer C; also the engine behind the GitHub Action (docker.yml).
3. GitHub Action (ChibaYuki347/pptgenerator-cli@v*) — Docker-based; just declare input / output and the action handles the rest. See action.yml.

License

MIT.