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.

## CRITICAL: Read All Documentation First

**Before starting any presentation task**, read ALL relevant documentation files completely to understand the full workflow:

1. **For creating new presentations**: Read [`html2pptx.md`](html2pptx.md) and [`css.md`](css.md) in their entirety
2. **For editing existing presentations**: Read [`ooxml.md`](ooxml.md) in its entirety
3. **For template-based creation**: Read the relevant sections of this file plus [`css.md`](css.md)

**NEVER set any range limits when reading these files.** Understanding the complete workflow, constraints, and best practices before starting is essential for producing high-quality presentations. Partial knowledge leads to errors, inconsistent styling, and visual defects that require rework.

## 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/public/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. **Read documentation**: Read [`html2pptx.md`](html2pptx.md) and [`css.md`](css.md) completely (see "CRITICAL: Read All Documentation First" section above)

2. **PREREQUISITE - Extract html2pptx library**:
   - Extract the library next to your script: `mkdir -p html2pptx && tar -xzf skills/public/pptx/html2pptx.tgz -C html2pptx`
   - This creates a `html2pptx/` directory with the library files and CLI binaries

3. **Plan the presentation**: Follow html2pptx.md "Design Philosophy" section for:
   - Aesthetic direction and bold design choices
   - Color palette selection (see "Creating your color palette")
   - Typography strategy
   - Write DETAILED outline with slide layouts and presenter notes (1-3 sentences per slide)

4. **Set CSS variables**: Override CSS variables in a shared `.css` file for colors, typography, and spacing (see css.md "Design System Variables")

5. **Create HTML slides** (960px × 540px for 16:9): Follow html2pptx.md for:
   - Slide layout zones (title, content, footnote)
   - Critical text rules (proper HTML tags)
   - Supported elements and styling

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("./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**: Convert to images and inspect for layout issues
   - Convert PPTX to PDF first: `soffice --headless --convert-to pdf output.pptx`
   - Then convert PDF to images: `pdftoppm -jpeg -r 150 output.pdf slide`
     - This creates files like `slide-1.jpg`, `slide-2.jpg`, etc.
   - Read each generated image file and carefully examine 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
     - **Alignment problems**: Elements not properly aligned with each other
     - **Visual hierarchy**: Important content properly emphasized
   - **CRITICAL: All slides MUST pass these validation checks before delivering to the user.** Do not skip this step or deliver presentations with visual defects.
   - If issues found, fix them in the following order of priority:
     1. **Increase margins** - Add more padding/spacing around problematic elements
     2. **Adjust font size** - Reduce text size to fit within available space
     3. **Rethink the layout entirely** - If the above fixes don't work, redesign the slide layout
   - Regenerate the presentation after making changes
   - 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. **Read documentation**: Read [`ooxml.md`](ooxml.md) completely (see "CRITICAL: Read All Documentation First" section above)
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: `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 grid**:

   - Extract text: `python -m markitdown template.pptx > template-content.md`
   - Read `template-content.md` completely to understand the template contents
   - Create thumbnail grids: `python scripts/thumbnail.py template.pptx`
   - See [Creating Thumbnail Grids](#