deck3d

deck3d

Turn a Markdown outline into one self-contained, offline deck.html: extruded 3D titles, harvested mermaid diagrams built as 3D objects, animated backgrounds, and an optional glTF prop. The converter code is deterministic; you tune the result by writing overrides in deck.json, never by editing the HTML.

When to use

• The user has an existing .pptx: follow deck3d-from-pptx (import, reference renders, then a variant-and-ask step per styling decision).
• The user has a Markdown outline (headings + bullets + ```mermaid blocks) and wants a presentation they can open offline in a browser.
• You need to tune placement, legibility, mode, effects or props of an existing deck.json.

Markdown grammar

• --- front-matter: deck defaults (mode, palette, material, quality, transition, …).
• # Title starts a slide. Zero headings ⇒ one slide id slide.
• The first paragraph after the heading (before bullets) is the subtitle.
• - bullet lines are body bullets.
• A fenced ```mermaid flowchart / sequenceDiagram block becomes the slide's diagram (harvested in headless chromium). Any other diagram type ⇒ warn + no diagram.
• <!-- deck3d: {...} --> inline overrides win over deck.json and warn on clobber. The comment may span several lines or be written as a bullet (- <!-- deck3d: {...} -->); in every form it is read as an override and is never the subtitle or a bullet.
• Pin a slide id with # Final {#outro} so renames never orphan tuning.

The tune loop

Interactive authoring path: deck3d serve talk.md [--check]. Watches sources, rebuilds on change, reloads in place, re-pins local fx hashes, and lets the configurator save or apply overrides directly.

Manual headless / agent / CI path:

1. deck3d parse talk.md → talk.json (derived IR + empty overrides).
2. deck3d validate talk.json → schema + derived-edit + orphan/prop warnings.
3. deck3d build talk.md -o talk.html → talk.json + talk.html; runs check and prints style: <n>/<N> slides styled.
4. Style — mandatory, and the step that decides whether the deck looks designed. deck3d check talk.html --style warns style-defaults for every slide still running only what parse chose. For each one:
   • pick a corpus effect (deck3d fx list --topic geo, --kind background; the stylistic set — clipped-solids, extruded-shapes, volume-cloud, curve-flow, … — is never auto-picked, so it is always an explicit choice) or write a per-deck one with deck3d fx scaffold <name> --for <slideId>;
   • give a content slide without a mermaid block a built topology (overrides.slides["<id>"].diagram.kind + data);
   • illustrate the section: deck3d props search <kw> --role hero, --role illustration, and props search --role ambient for low-triangle background instances;
   • if extruded titles read as a solid block, set titleEdge: "contrast" (deck default, or per slide) — it outlines every character in the palette text colour;
   • for a deck that wants a horizon, set overrides.deck.floor: "water" (one global surface; per-slide is not a thing);
   • the floor reflects the backgrounds too; overrides.deck.reflectBackdrop: false limits the reflection to slide content (one less backdrop pass per frame), and overrides.deck.floorMatte (0-1) roughens it — 0 is a perfect mirror, ~0.35 reads as polished concrete, ~0.85 as scattered stone (the ⚙ panel drags it on a slider), while overrides.deck.floorReflectivity (0-1, default 1) sets how STRONG the reflection is; all deck-scope only;
   • grade the frame with a post card (deck3d fx list --kind post): add { "id": "outline", "params": { "parts": "diagram" } } (or selective-bloom, god-rays, depth-of-field, pixelate, ascii, …) to the slide's effects[]. One or two per slide; they stack in a fixed order, and check flags declared conflicts.
5. Read the check findings. Fix only the suggested key (e.g. overrides.slides["arch"].diagram.scale), then re-run step 3.
6. deck3d snapshot talk.html --slide 5 -o s5.png to eyeball one slide.
7. Repeat until check is clean and the style line accounts for every slide you meant to design.