pptx

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

`python3 ooxml/scripts/unpack.py <office_file> <output_dir>`

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