pptxgenjs Compatibility Skill
Generate PowerPoint-compatible PPTX files using pptxgenjs without triggering repair dialogs.
The Core Problem
pptxgenjs has 6 known defects (GitHub Issue #1449) that cause PowerPoint to show the "problem with content" repair dialog. The defects are baked into the library's XML generation and cannot be avoided at the JavaScript level. A mandatory post-processing step is required after every PPTX generation.
Workflow
Step 1: Generate PPTX with Safe API Patterns
When writing pptxgenjs code, follow these rules to minimize (but not eliminate) compatibility issues:
Forbidden APIs (will cause cross-version issues)
❌ shadow — generates complex OOXML effect chains unsupported in many PowerPoint versions
❌ transparency — inconsistent behavior across PowerPoint/WPS/LibreOffice versions
❌ String shape names like "oval", "roundedRectangle" — writes invalid prstGeom values
Safe Alternatives
✅ Use line borders instead of shadow for visual depth
✅ Use pre-mixed colors instead of transparency (calculate blended colors on dark backgrounds)
✅ Pre-render dimmed icon variants (dark PNG) instead of runtime image transparency
✅ Always use enum constants: pres.shapes.OVAL, pres.shapes.ROUNDED_RECTANGLE
Pre-mixed Color Calculation
To replace transparency on a dark background, calculate the blended color:
background #1A1A2E + white at 20% opacity → approximately #3A3A4E
For dimmed icons, render at design time with a dark color:
const iconDim = await iconToBase64Png(FaShield, "3A4450", 256); // dark variant
Step 2: Post-Process with fix_pptx_compatibility.py
This step is MANDATORY. Even with perfect API usage, pptxgenjs generates invalid XML that must be fixed.
Run the bundled script:
python scripts/fix_pptx_compatibility.py <input.pptx> [output.pptx]
If output is omitted, the input file is overwritten in place.
The script fixes all 6 known defects:
- Phantom slideMaster overrides in
[Content_Types].xml — the #1 cause of repair dialogs. pptxgenjs registers non-existent slideMaster2~N.xml for every slide
- Invalid theme font references — replaces
+mn-lt, +mn-ea, +mn-cs, +mj-lt, +mj-ea, +mj-cs with Microsoft YaHei
- dirty= attribute — removes non-standard pptxgenjs attribute
- p14:modId elements — removes non-standard namespace elements
- Notes Slides/Masters — removes broken notes files and their relationship references
- Zero-extent shapes and empty elements — fixes
cx="0" cy="0", <a:t></a:t>, <a:ln />
Step 3: Verify
Open the PPTX in PowerPoint to confirm no repair dialog appears. For automated verification, check:
- All Override PartNames in
[Content_Types].xml point to existing files
- No
+mn-lt style font references remain
- No
dirty= attributes remain
- No
p14: namespace prefixes remain in slide XMLs
Common Mistakes to Avoid (Lessons from Real Incidents)
- Don't assume shadow/transparency fixes are enough — The real root cause is usually phantom slideMaster overrides in Content_Types.xml, not visual effects
- Don't write validation scripts with
max() fallback to 0 for -1 values — This causes false positives in element order checks
- Don't use single-line regex for XML that spans multiple lines — Use
re.DOTALL flag
- Don't skip post-processing — Even if the PPTX looks fine in your version of PowerPoint, it may break in others
- Search for known issues FIRST — Before diagnosing compatibility problems from scratch, check GitHub Issues for the library
Reference
For the complete list of pptxgenjs defects with examples and fixes, see references/pptxgenjs-pitfalls.md.
