PPTX creation, editing, and analysis

Overview

Create, edit, or analyze the contents of .pptx files when requested. A .pptx file is essentially a ZIP archive containing XML files and other resources. Different tools and workflows are available for different tasks.

Reading and analyzing content

Text extraction

To read just the text content of a presentation, convert the document to markdown:

# Convert document to markdown
python -m markitdown path-to-file.pptx

Raw XML access

Use raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. To access these features, unpack a presentation and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_dir>

Note: The unpack.py script is located at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script doesn't exist at this path, use find . -name "unpack.py" to locate it.

Key file structures

• ppt/presentation.xml - Main presentation metadata and slide references
• ppt/slides/slide{N}.xml - Individual slide contents (slide1.xml, slide2.xml, etc.)
• ppt/notesSlides/notesSlide{N}.xml - Speaker notes for each slide
• ppt/comments/modernComment_*.xml - Comments for specific slides
• ppt/slideLayouts/ - Layout templates for slides
• ppt/slideMasters/ - Master slide templates
• ppt/theme/ - Theme and styling information
• ppt/media/ - Images and other media files

Typography and color extraction

To emulate example designs, analyze the presentation's typography and colors first using the methods below:

1. Read theme file: Check ppt/theme/theme1.xml for colors (<a:clrScheme>) and fonts (<a:fontScheme>)
2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colors
3. Search for patterns: Use grep to find color (<a:solidFill>, <a:srgbClr>) and font references across all XML files

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Workflow

1. MANDATORY - READ ENTIRE FILE NOW: Read html2pptx.md completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.

2. PREREQUISITE - Install html2pptx library:

   • Check and install if needed: npm list -g @ant/html2pptx || npm install -g skills/pptx/html2pptx.tgz
   • Note: If you see "Cannot find module '@ant/html2pptx'" error later, the package isn't installed

3. CRITICAL: Plan the presentation

   • Plan the shared aspects of the presentation. Describe the tone of the presentation's content and the colors and typography that should be used in the presentation.
   • Write a DETAILED outline of the presentation
   • For each slide, describe the slide's layout and contents
   • For each slide, write presenter notes (1 to 3 sentences per slide)

4. CRITICAL: Set CSS variables

   • In a shared .css file, override CSS variables to use on each slide for colors, typography, and spacing. DO NOT create classes in this file.

5. Create an HTML file for each slide with proper dimensions (e.g., 960px × 540px for 16:9)

   • Recall the outline, layout/content description, and speaker notes you wrote for this slide in Step 3. Think out loud how to best apply them to this slide.
   • Embed the contents of the shared .css file in a <style> element
   • Use <p>, <h1>-<h6>, <ul>, <ol> for all text content
   • IMPORTANT: Use CSS variables for colors, typography, and spacing
   • IMPORTANT: Use row col and fit classes for layout INSTEAD OF flexbox
   • Use class="placeholder" for areas where charts/tables will be added (render with gray background for visibility)
   • CSS gradients: Use linear-gradient() or radial-gradient() in CSS on block element backgrounds - automatically converted to PowerPoint
   • Background images: Use background-image: url(...) CSS property on block elements
   • Block elements: Use <div>, <section>, <header>, <footer>, <main>, <article>, <nav>, <aside> for containers with styling (all behave identically)
   • Icons: Use inline SVG format or reference SVG files - SVG elements are automatically converted to images in PowerPoint
   • Text balancing: <h1> and <h2> elements are automatically balanced. Use data-balance attribute on other elements to auto-balance line lengths for better typography
   • Layout: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability

6. Create and run a JavaScript file using the html2pptx library to convert HTML slides to PowerPoint and save the presentation

   • Run with: NODE_PATH="$(npm root -g)" node your-script.js 2>&1

   • Use the html2pptx function to process each HTML file

   • Add charts and tables to placeholder areas using PptxGenJS API

   • Save the presentation using pptx.writeFile()

   • ⚠️ CRITICAL: Your script MUST follow this example structure. Think aloud before writing the script to make sure that you correctly use the APIs. Do NOT call pptx.addSlide.

   const pptxgen = require("pptxgenjs");
   const { html2pptx } = require("@ant/html2pptx");
   
   // Create a new pptx presentation
   const pptx = new pptxgen();
   pptx.layout = "LAYOUT_16x9"; // Must match HTML body dimensions
   
   // Add an HTML-only slide
   await html2pptx("slide1.html", pptx);
   
   // Add a HTML slide with chart placeholders
   const { slide: slide2, placeholders } = await html2pptx("slide2.html", pptx);
   slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
   
   // Save the presentation
   await pptx.writeFile("output.pptx");
   

7. Visual validation: Generate thumbnails and inspect for layout issues

   • Create thumbnail grid: python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • Read and carefully examine the thumbnail image for:
     • Text cutoff: Text being cut off by header bars, shapes, or slide edges
     • Text overlap: Text overlapping with other text or shapes
     • Positioning issues: Content too close to slide boundaries or other elements
     • Contrast issues: Insufficient contrast between text and backgrounds
   • If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
   • Repeat until all slides are visually correct

Editing an existing PowerPoint presentation

To edit slides in an existing PowerPoint presentation, work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
2. Unpack the presentation: python ooxml/scripts/unpack.py <office_file> <output_dir>
3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
4. CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding: python ooxml/scripts/validate.py <dir> --original <file>
5. Pack the final presentation: python ooxml/scripts/pack.py <input_directory> <office_file>

Creating a new PowerPoint presentation using a template

To create a presentation that follows an existing template's design, duplicate and re-arrange template slides before replacing placeholder content.

Workflow

1. **Extract template text AND create visual thumbnail gri