yamldeck

Local-first YAML to editable PowerPoint decks.

yamldeck is a CLI tool for generating usable .pptx slide decks from compact YAML specs. It is designed for workflows where a small local LLM writes the deck spec and yamldeck handles layout, themes, resources, pagination, and PowerPoint generation on-device.

This is especially useful for sensitive content: the themes can be generated by large design models and the slides (and sensitive data inside them) can be generated by small local LLMs as long as they are capable of bash tool calling.

Quick Start

npm install
node js/cli.mjs list-themes --minimal
node js/cli.mjs describe-layout chart --minimal
node js/cli.mjs validate examples/showcase/startup_pitch.yaml
node js/cli.mjs build examples/showcase/startup_pitch.yaml -o examples/showcase/outputs/startup_pitch.pptx

Create a starter YAML spec:

node js/cli.mjs new --theme executive -o scratch.yaml

With an installed theme directory:

node js/cli.mjs list-themes --theme-dir installed_js_themes
node js/cli.mjs build examples/theme_gallery/mono_demo.yaml -o examples/theme_gallery/outputs/mono_demo.pptx --theme-dir installed_js_themes

YAML Shape

title: Product Adoption Snapshot
theme: clean
slides:
  - layout: cover
    title: Product Adoption Snapshot
    subtitle: Activation, retention, and next experiments.
  - layout: metric_row
    title: Adoption at a glance
    metrics:
      - label: Activation
        value: 57%
        note: +16 pts

Resources can be declared once and referenced by key:

resources:
  product_shot: ../assets/product.png
slides:
  - layout: image
    title: Product view
    image: product_shot

The CLI embeds image bytes into the PPTX. The generated deck does not depend on the original image path.

Why This Exists

Small local LLMs are often good enough to structure slide content, but not good at writing robust PowerPoint code or making consistent design decisions. The intended division of labor is:

small local LLM -> compact YAML
yamldeck        -> validation, layout, theme rendering, embedded PPTX

The slides are meant to be clean, readable, and usable rather than highly original. Theme variety exists, but the priority is reliable local generation for private or sensitive material.

Discovery Commands

These commands are optimized for low-context LLM agents.

node js/cli.mjs list-themes --minimal
node js/cli.mjs list-themes --layout quote --minimal
node js/cli.mjs themes-for-layout chart --minimal
node js/cli.mjs list-layouts editorial --minimal
node js/cli.mjs search-layouts metric --minimal
node js/cli.mjs describe-layout chart --minimal
node js/cli.mjs describe-theme editorial --minimal

Output modes:

• default: readable tabular text
• --minimal / --min: compact key:value lines for low-token agents
• --json: structured JSON when a caller needs parsing

Core Layouts

Every theme implements:

• cover
• section
• statement
• bullets
• metric_row
• comparison
• chart
• table
• timeline
• image

Themes may add custom layouts. Use discovery commands before using a theme-specific layout.

Themes

Built-in themes:

• clean
• editorial
• executive
• forest
• midnight
• minimal
• playful

External .mjs themes can be loaded with --theme-dir.

For detailed theme creation instructions, see THEME_AUTHORING.md.

Auto Pagination

The engine splits oversized repeatable content into continuation slides before rendering. Agents can provide the natural full list instead of manually counting items.

Default split points:

• bullets: 6 items per slide
• metric_row: 4 metrics per slide
• comparison: 5 bullets per side per slide
• table: 8 rows per slide
• timeline: 5 events per slide

Themes can override or add pagination rules with layoutPagination, but the splitting behavior is centralized in the engine.

Resources

Deck specs can define resources:

resources:
  hero: ../assets/hero.png

Themes can also define resources:

export const clean = {
  name: "clean",
  resources: {
    sample_image: "assets/clean-sample.png",
  },
  tokens,
  layouts,
};

Layouts can reference deck resources, theme resources, direct paths, data URIs, or { path } objects. The resolver converts image resources to data URIs and passes those to pptxgenjs, so the PPTX contains the image itself.

Additional lookup folders:

node js/cli.mjs build spec.yaml -o deck.pptx --resource-dir assets

Examples

examples/
  showcase/       varied real-use decks
    outputs/
  theme_gallery/  built-in and installed theme demos
    outputs/

Run all examples:

npm run build:examples