Data Presentations

Build polished PowerPoint slide decks — from scratch or by editing existing templates.

Decide Your Path

There are three execution paths. Pick the one that matches the task:

Task	Path	Tools
Build a new deck from nothing	Create (pptxgenjs, JavaScript)	Node.js script
Modify an existing .pptx file	Edit (unpack XML, edit, repack)	Python scripts + Edit tool
Read or analyze a .pptx file	Read (markitdown + thumbnails)	Python scripts

---

Path 1: Create from Scratch

Use when no template or reference file is provided.

Workflow

1. Plan the deck — decide slide count, layout variety, color palette, and typography. See references/design-principles.md for palettes, font pairings, layout patterns, and spacing rules.

2. Write a Node.js script that uses pptxgenjs to generate the deck. The script should be a standalone .js file the user can keep and re-run. See references/pptxgenjs-api.md for the full API reference including text, shapes, images, icons, charts, tables, and slide masters.

3. Run it:

   node generate-slides.js
   

4. Run visual QA — see the QA section below. The first render always has problems.

Critical Rules (create path)

• All coordinates and dimensions are in inches
• Hex colors have no # prefix — "FF0000" not "#FF0000"
• Never encode opacity in the color string — use the opacity property
• Use breakLine: true between text array items, not \n
• Use bullet: true, never unicode "•" characters
• Use charSpacing not letterSpacing (the latter is silently ignored)
• Set margin: 0 on text boxes when aligning precisely with shapes/icons
• Never reuse option objects across calls — pptxgenjs mutates them in-place. Use factory functions: const makeShadow = () => ({ ... })
• Shadow offset must be non-negative — use angle: 270 for upward shadows
• Don't pair ROUNDED_RECTANGLE with rectangular accent overlays

---

Path 2: Edit an Existing Presentation

Use when the user provides a .pptx file to modify or a template to populate.

Workflow

1. Analyze the file:

   python scripts/thumbnail.py input.pptx
   python -m markitdown input.pptx
   

   Review the thumbnail grid to see layouts. Review markitdown output for text content.

2. Unpack:

   python scripts/office/unpack.py input.pptx unpacked/
   

3. Structural changes first (before editing any content):

   • Duplicate slides you need: python scripts/office/add_slide.py unpacked/ slide2.xml
   • Delete unwanted slides: remove their <p:sldId> from ppt/presentation.xml
   • Reorder: rearrange <p:sldId> elements within <p:sldIdLst>

4. Edit content — read each slide's XML, find placeholder text, replace with final content. Use the Edit tool for all XML changes. See references/xml-editing.md for formatting rules.

5. Clean:

   python scripts/clean.py unpacked/
   

6. Pack:

   python scripts/office/pack.py unpacked/ output.pptx --original input.pptx
   

7. Run visual QA — see below.

Critical Rules (edit path)

• Use the Edit tool for XML changes, not sed or Python string manipulation
• Each bullet/item needs its own <a:p> — never concatenate into one text run
• Copy <a:pPr> from original paragraphs to preserve line spacing
• Use smart quote entities: “ ” ‘ ’
• Use xml:space="preserve" on <a:t> elements with leading/trailing spaces
• If template has more items than your content, remove excess elements entirely
• Never manually copy slide files — always use add_slide.py

---

Path 3: Read and Analyze

# Extract all text
python -m markitdown presentation.pptx

# Visual thumbnail grid
python scripts/thumbnail.py presentation.pptx

# Raw XML access
python scripts/office/unpack.py presentation.pptx unpacked/

---

Visual QA

The first render always has problems. Your job is to find them.

Convert to images

python scripts/office/soffice.py input.pptx output.pdf
rm -f slide-*.jpg
pdftoppm -jpeg -r 150 output.pdf slide
ls -1 "$PWD"/slide-*.jpg

Always rm -f slide-*.jpg first to clear stale images. After fixes, rerun all four commands.

What to check

Inspect every slide image for:

• Overlapping elements
• Text overflow or cut-off
• Decorative elements that don't accommodate wrapped text
• Elements too close (< 0.3" gaps) or uneven spacing
• Insufficient margin from edges (< 0.5")
• Low-contrast text or icons
• Leftover placeholder content

Check for placeholders:

python -m markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert"

Verification loop

1. Generate/edit slides, convert to images, inspect
2. List all issues found
3. Fix issues
4. Re-verify — one fix often creates a new problem
5. Repeat until a full pass reveals no new issues

Do not declare success until at least one full fix-and-verify cycle completes.

---

Reference Documents

These contain detailed API docs, loaded on demand:

• references/pptxgenjs-api.md — full pptxgenjs creation API
• references/xml-editing.md — XML editing rules and patterns
• references/design-principles.md — color palettes, typography, layout patterns
• references/visual-qa.md — detailed QA checklist and process