| name | creating-presentations |
| description | Use when creating, editing, or analyzing PowerPoint presentations (.pptx files). Supports three workflows: (1) HTML-to-PPTX for new presentations with custom design, (2) Template-based for using existing corporate templates, (3) OOXML editing for precise modifications to existing files. |
| version | 2.0 |
| license | Proprietary. LICENSE.txt has complete terms |
Creating Presentations
Overview
Transform content into professional PowerPoint presentations. A .pptx file is a ZIP archive containing XML files—edit directly for precise control, or use html2pptx for rapid design-driven creation.
Core Principle: Choose the right workflow for the task. New presentations with custom design → html2pptx. Existing templates → template workflow. Precise edits → OOXML.
When to Use
- Creating new presentations from scratch
- Editing existing .pptx files (text, images, layouts)
- Analyzing presentation content and structure
- Working with corporate templates
- Adding charts, tables, or speaker notes
Don't use for:
- PDF-only output (use other tools)
- Simple text extraction only (use
python -m markitdown file.pptx)
Quick Reference
| Task | Command/Action |
|---|
| Extract text | python -m markitdown file.pptx |
| Create thumbnails | python scripts/thumbnail.py file.pptx |
| Unpack for editing | python ooxml/scripts/unpack.py file.pptx output_dir |
| Repack after edit | python ooxml/scripts/pack.py input_dir file.pptx |
| Validate changes | python ooxml/scripts/validate.py dir --original file.pptx |
| Rearrange slides | python scripts/rearrange.py template.pptx output.pptx 0,1,3,1 |
| Extract text inventory | python scripts/inventory.py file.pptx inventory.json |
| Replace text | python scripts/replace.py file.pptx replacements.json output.pptx |
| Apply Keynote style | python scripts/apply-keynote-layouts.py keynote.pptx generated.pptx output.pptx |
Workflow Selection
Workflow 1: HTML-to-PPTX (New Presentations)
Best for: Creating presentations with custom design, full creative control.
- Read reference: Load
html2pptx.md completely
- Design approach: State color palette and design choices BEFORE coding
- Create HTML slides: One HTML file per slide (720pt × 405pt for 16:9)
- Convert: Use
html2pptx.js to generate PowerPoint
- Validate: Create thumbnail grid and inspect for issues
Critical rules:
- ALL text must be in
<p>, <h1>-<h6>, <ul>, <ol> tags
- Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Verdana
- Pre-rasterize gradients and icons as PNG (CSS gradients don't convert)
- No
# prefix in PptxGenJS hex colors
Workflow 2: Template-Based (Corporate Templates)
Best for: Using existing branded templates, consistent styling.
- Analyze template:
python -m markitdown template.pptx > template-content.md
python scripts/thumbnail.py template.pptx
- Create inventory: Document each slide layout with purpose
- Plan outline: Map content to template slides
- Rearrange slides:
python scripts/rearrange.py template.pptx working.pptx 0,5,5,12
- Extract text:
python scripts/inventory.py working.pptx text-inventory.json
- Generate replacements: Create JSON with new text content
- Apply changes:
python scripts/replace.py working.pptx replacements.json output.pptx
Template inventory format:
# Template Inventory
**Total Slides: [count]** (0-indexed)
## Title Slides
- Slide 0: Cover - Full image background with title overlay
- Slide 1: Section divider - Colored background with centered text
## Content Slides
- Slide 5: Two columns - Left text, right image placeholder
- Slide 12: Bullet list - Title with 3-5 bullet points
Workflow 3: Keynote Style Merge (Apply Keynote Templates)
Best for: Applying Keynote-designed templates to generated PPTX, Keynote compatibility.
Problem solved: When you generate PPTX with html2pptx but need:
- Keynote template backgrounds and decorative elements
- Proper display when opened in Keynote (canvas size matching)
- Different layouts for different slide types (cover, content, thanks, etc.)
Process:
-
Prepare Keynote template: Export your Keynote file as PPTX
- File → Export To → PowerPoint
- This preserves slide layouts with backgrounds
-
Generate content PPTX: Use html2pptx workflow to create content
-
Merge styles:
python scripts/apply-keynote-layouts.py keynote_template.pptx generated.pptx output.pptx
What the script does:
- Copies theme, slide masters, layouts, and media from Keynote template
- Scales content to match Keynote's larger canvas (typically 2.67x)
- Analyzes each slide to determine type (cover, section, content, thanks)
- Maps slides to appropriate Keynote layouts with matching backgrounds
- Removes inline backgrounds so slides inherit from layouts
- Applies optimal font scaling (2.2x) to balance readability vs overflow
Layout mapping (customizable in script):
| Slide Type | Layout | Detection |
|---|
| cover | 1 | Contains "讲师", "时长" |
| section_title | 2 | Contains "Part", "第", "章" with short text |
| thanks | 16 | Contains "Q&A", "感谢", "谢谢", "总结" |
| simple_content | 4 | ≤3 shapes |
| content | 5 | 4-5 shapes |
| multi_element | 10 | 6-7 shapes |
| complex | 11 | >7 shapes |
Key parameters:
font_scale: Default 2.2x. Adjust if text overflows (lower) or too small (higher)- Layout mapping: Edit
get_layout_mapping() function for custom templates
Best practices:
- Canvas scaling is automatic based on size difference
- Font scaling should be ~80% of canvas scaling to prevent overflow
- Test with a few slides first before processing entire deck
Workflow 4: OOXML Direct Edit (Precise Modifications)
Best for: Surgical edits, comments, speaker notes, complex formatting.
- Read reference: Load
ooxml.md completely
- Unpack:
python ooxml/scripts/unpack.py file.pptx unpacked_dir
- Edit XML: Modify files in
ppt/slides/, ppt/notesSlides/, etc.
- Validate:
python ooxml/scripts/validate.py unpacked_dir --original file.pptx
- Repack:
python ooxml/scripts/pack.py unpacked_dir output.pptx
Key file locations:
ppt/slides/slide{N}.xml - Slide contentppt/notesSlides/notesSlide{N}.xml - Speaker notesppt/comments/ - Commentsppt/theme/theme1.xml - Colors and fonts
Design Principles
OpenMind Course Design System
OpenMind course presentations must follow the visual specifications defined in openmind-design-system.md:
Core Color Palette:
| Role | Value | Usage |
|---|
| Primary Blue | #2563EB | Core concepts, titles, primary CTAs |
| Accent Gold | #F59E0B | Secondary highlights, layer indicators |
| Dark Slate | #1E293B | Core insight cards |
| Text Gray | #666666 | Descriptions |
| White BG | #FFFFFF | Standard content pages |
| Warm Yellow BG | #FFF9E6 | Code demo pages |
Typography Scale:
- Hero title (covers): 72pt
- Page title: 36pt
- Card title: 24-30pt
- Body text: 16-18pt
- Footer: 14pt
Layout Patterns:
- Centered Title - Chapter covers
- Title + Three Cards - Comparisons/categories
- Stepped Layers - Hierarchy progression
- Left-Right Split - Code + explanation
- Formula Layout - Concept derivation
Color Palette Selection
Before creating, analyze content and choose appropriate palette:
- Consider subject matter, tone, industry
- Check for brand requirements
- Select 3-5 colors: dominant + supporting + accent
- Ensure text contrast on backgrounds
Example palettes:
- OpenMind Standard: #2563EB, #F59E0B, #1E293B, #FFFFFF
- Classic Blue: #1C2833, #2E4053, #AAB7B8, #F4F6F6
- Teal & Coral: #5EA8A7, #277884, #FE4447, #FFFFFF
- Warm Blush: #A49393, #EED6D3, #E8B4B8, #FAF7F2
- Black & Gold: #BF9A4A, #000000, #F4F6F6
Layout Guidelines
For slides with charts/tables:
- Two-column (preferred): Header spanning full width, text + chart side-by-side
- Full-slide: Chart/table takes entire slide for maximum impact
- Never stack: Don't place charts below text in single column
Common Mistakes
| Mistake | Impact | Fix |
|---|
Text in <div> not <p> | Text missing in output | Wrap all text in <p>, <h1>-<h6>, <ul>, <ol> |
| CSS gradients | Won't render | Pre-rasterize to PNG with Sharp |
# in PptxGenJS colors | File corruption | Use "FF0000" not "#FF0000" |
| Custom fonts | Rendering issues | Use web-safe fonts only |
| Wrong slide index | Wrong template used | Remember 0-indexed (first slide = 0) |
| Skip validation | Broken files | Always validate after OOXML edits |
Resources
Scripts
| Script | Purpose |
|---|
scripts/html2pptx.js | Convert HTML slides to PowerPoint |
scripts/thumbnail.py | Generate slide thumbnail grids |
scripts/rearrange.py | Duplicate/reorder/delete slides |
scripts/inventory.py | Extract text inventory as JSON |
scripts/replace.py | Apply text replacements from JSON |
scripts/apply-keynote-layouts.py | Merge Keynote template styles into generated PPTX |
ooxml/scripts/unpack.py | Unpack .pptx to XML directory |
ooxml/scripts/pack.py | Repack XML directory to .pptx |
ooxml/scripts/validate.py | Validate OOXML structure |
References
html2pptx.md - Complete HTML-to-PPTX guide with syntax, styling, chartsooxml.md - Office Open XML technical reference for direct editingopenmind-design-system.md - OpenMind Course Design Spec with color palette, typography, layout templates
Dependencies
pip install "markitdown[pptx]" defusedxml
npm install -g pptxgenjs playwright sharp react-icons react react-dom
