pptx-profile

Step 1 — Profile (pptx-profile)

Turn any .pptx into a map of its real layouts so the next steps can target them precisely. This is the answer to "what layouts does my template actually have, and what is each one for?"

  STEP 1 — PROFILE          STEP 2 — AUTHOR           STEP 3 — RENDER
  pptx-profile              pptx-author               pptx-from-layouts
  ───────────────           ───────────────           ─────────────────
  your-template.pptx        slides.md (+ [HINT:])     slides.md + config
        │                         │                         │
        ▼                         ▼                         ▼
   catalog.py  ──catalog.md──▶  write & lint  ──slides──▶  generate.py ─▶ deck.pptx
        └────────────────── config.json ───────────────────▲   (validated)
  "what layouts do I        "write slides that        "fill the template's
   have?"                    name real layouts"        actual placeholders"

You are here: Step 1. Output feeds Steps 2 and 3.

Dependencies

Python 3.10+ and python-pptx (pip install python-pptx). The config step shells out to the sibling pptx-from-layouts skill, which ships in this repo.

Run it

python scripts/catalog.py /path/to/your-template.pptx \
    --name your-template --output-dir ./build

This writes two files into ./build:

File	For whom	Purpose
`your-template-layout-catalog.md`	you / Step 2 author	Human-readable menu of every hintable layout: its `[HINT:]` name, placeholders, and when to use it.
`your-template-config.json`	Step 3 render engine	Machine map of capability → real layout index/name. Passed to `generate.py --config`.

Options: --catalog-only skips the config (catalog only); --name sets the output basename (defaults to the filename).

What the catalog gives you

The catalog's Hintable layouts table lists only layouts the engine knows how to populate — every name there is a safe [HINT:] value. A collapsed section lists all raw layouts in the file for reference. Each row shows the layout index, the exact hint name to copy, its placeholders (e.g. picture, body, center-title), and a one-line "when to use".

Then what

Step 2 — author: open the catalog, write slides.md using [HINT: layout_name] per slide, and lint with pptx-author/scripts/lint_hints.py slides.md --config your-template-config.json.
Step 3 — render: pptx-from-layouts/scripts/generate.py slides.md -o deck.pptx --template your-template.pptx --config your-template-config.json --validate.

Notes

You only profile a template once. Reuse the catalog + config for every future deck on that template.
The bundled Inner Chapter template is already profiled (see templates/inner-chapter-config.json) and is the default if you skip Step 1.
For a fully automated, on-brand onboarding (brand colors, fonts, smoke-test), the pptx-template-onboarder subagent wraps this step.