pptx

What this skill does

# 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:

```bash
# 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`](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`](./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`.

   ```javascript
   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`](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 gr