pptx

PPTX creation, editing, and analysis

Overview

Users may ask you to create, edit, or analyze the contents of .pptx files. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. Different tasks have different tools and workflows available.

Reading and analyzing content

Text extraction

If you only need to read the text content of a presentation, you should convert the document to markdown:

# 将文档转换为 markdown
python -m markitdown path-to-file.pptx

Raw XML access

You need raw XML access to handle: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For these features, you need to unzip the presentation and read its raw XML content.

Unzip the file

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

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

Key file structure

ppt/presentation.xml - Main presentation metadata and slide references
ppt/slides/slide{N}.xml - Individual slide content (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/ - Slide layout templates
ppt/slideMasters/ - Master slide templates
ppt/theme/ - Theme and style information
ppt/media/ - Images and other media files

Typography and color extraction

When an example design to imitate is provided: Always first analyze the presentation's typography and colors using the following methods:

Read the theme file: Check ppt/theme/theme1.xml for colors (<a:clrScheme>) and fonts (<a:fontScheme>）
Sample slide content: Check ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colors
Search patterns: Use grep to find colors (<a:solidFill>、<a:srgbClr>) and font references in all XML files

Creating a new PowerPoint presentation without using a template

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

Design principles

Key: Before creating any presentation, analyze the content and choose appropriate design elements:

Consider the topic: What is this presentation about? What tone, industry, or mood does it suggest?
Check the brand: If the user mentions a company/organization, consider its brand colors and identity
Match the palette to the content: Choose colors that reflect the topic
Explain your approach: Explain your design choices before writing code

Requirements：

✅ Explain your content-based design approach before writing code
✅ Use only web-safe fonts: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
✅ Create clear visual hierarchy through size, weight, and color
✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
✅ Maintain consistency: repeat patterns, spacing, and visual language between slides

Color Palette Selection

Choose colors creatively：

Go beyond default thinking: What colors truly match this specific theme? Avoid automatic choices.
Consider multiple angles: theme, industry, mood, energy level, target audience, brand identity (if mentioned)
Be bold: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy blue
Build the palette: Choose 3-5 colors that work well together (primary + secondary + accent)
Ensure contrast: Text must be clearly readable on the background

Example Palettes(to spark creativity - choose one, adapt it, or create your own):

Classic Blue: Deep Navy Blue (#1C2833), Slate Gray (#2E4053), Silver (#AAB7B8), Off-White (#F4F6F6)
Teal and Coral: Teal (#5EA8A7), Dark Teal (#277884), Coral (#FE4447), White (#FFFFFF)
Bold Red: Red (#C0392B), Bright Red (#E74C3C), Orange (#F39C12), Yellow (#F1C40F), Green (#2ECC71)
Warm Blush: Taupe (#A49393), Blush (#EED6D3), Rose (#E8B4B8), Cream (#FAF7F2)
Burgundy Luxury: Burgundy (#5D1D2E), Deep Red (#951233), Rust (#C15937), Gold (#997929)
Deep Purple and Emerald: Purple (#B165FB), Deep Blue (#181B24), Emerald (#40695B), White (#FFFFFF)
Cream and Forest Green: Cream (#FFE1C7), Forest Green (#40695B), White (#FCFCFC)
Pink and Purple: Pink (#F8275B), Coral (#FF574A), Rose (#FF737D), Purple (#3D2F68)
Lime and Plum: Lime (#C5DE82), Plum (#7C3A5F), Coral (#FD8C6E), Blue Gray (#98ACB5)
Black and Gold: Gold (#BF9A4A), Black (#000000), Cream (#F4F6F6)
Sage and Terracotta: Sage (#87A96B), Terracotta (#E07A5F), Cream (#F4F1DE), Charcoal (#2C2C2C)
Charcoal and Red: Charcoal (#292929), Red (#E33737), Light Gray (#CCCBCB)
Vibrant Orange: Orange (#F96D00), Light Gray (#F2F2F2), Charcoal (#222831)
Forest Green: Black (#191A19), Green (#4E9F3D), Dark Green (#1E5128), White (#FFFFFF)
Retro Rainbow: Purple (#722880), Pink (#D72D51), Orange (#EB5C18), Amber (#F08800), Gold (#DEB600)
Retro Earth: Mustard (#E3B448), Sage (#CBD18F), Forest Green (#3A6B35), Cream (#F4F1DE)
Coastal Rose: Old Rose (#AD7670), Beaver (#B49886), Eggshell (#F3ECDC), Gray-Green (#BFD5BE)
Orange and Teal-Green: Light Orange (#FC993E), Gray-Teal-Green (#667C6F), White (#FCFCFC)

Visual Detail Options

Geometric Patterns：

Diagonal dividers instead of horizontal dividers
Asymmetric column widths (30/70, 40/60, 25/75)
Text headings rotated 90° or 270°
Circular/hexagonal frames for images
Triangular decorative shapes in corners
Overlapping shapes to add depth

Border and Frame Treatments：

Thick monochrome border on one side only (10-20pt)
Double-line border in contrasting colors
Corner brackets instead of a full frame
L-shaped border (top+left or bottom+right)
Underline emphasis below headings (3-5pt thick)

Typography Treatments：

Extreme size contrast (72pt heading vs 11pt body text)
Uppercase headings with wide letter spacing
Numbered sections in oversized display type
Monospace font (Courier New) for data/statistics/technical content
Narrow font (Arial Narrow) for dense information
Outline text emphasis

Chart and Data Styles：

Monochrome charts with a single accent color for key data
Horizontal bar charts instead of vertical bar charts
Dot plots instead of bar charts
Minimal or no gridlines
Data labels directly on elements (no legend)
Oversized numbers for key metrics

Layout Innovation：

Full-bleed images with text overlay
Sidebar column (20-30% width) for navigation/context
Modular grid system (3×3, 4×4 blocks)
Z-shaped or F-shaped content flow
Floating text boxes over colored shapes
Magazine-style multi-column layout

Background Treatments：

Solid color blocks covering 40-60% of the slide
Gradient fills (vertical or diagonal only)
Split background (two colors, diagonal or vertical)
Edge-to-edge color bands
Negative space as a design element

Layout Tips

When creating slides with charts or tables：

Two-column layout (recommended): Use a heading that spans the full width, then two columns below - one column for text/bullet points, the other for the main content. This provides better balance and makes charts/tables easier to read. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize the space for each content type.
Full-slide layout: Let the main content (chart/table) occupy the entire slide for maximum impact and readability
Never stack vertically: Do not place charts/tables below text in a single column - this leads to poor readability and layout problems

Workflow

Must - read the entire file in full: Read the complete html2pptx.md, from beginning to end.Never set any range limits when reading this file. Before starting to create the presentation, read the complete file content to understand the detailed syntax, key formatting rules, and best practices.
Create HTML files with correct dimensions for each slide (e.g., 720pt × 405pt for 16:9)
- Use <p>、<h1>-<h6>、<ul>、<ol> to handle all text content
- Use class="placeholder"for areas where charts/tables will be added (render a gray background so they are visible)
- Key: First use Sharp to rasterize gradients and icons into PNG images, then reference them in the HTML
- Layout: For slides with charts/tables/images, use a full-slide layout or a two-column layout for better readability
Create and run a JavaScript file that uses the html2pptx.js library to convert HTML slides into PowerPoint and save the presentation
- Use html2pptx() function to process each HTML file
- Use the PptxGenJS API to add charts and tables to placeholder areas
- Use pptx.writeFile() to save the presentation
Visual verification: Generate thumbnails and check for layout issues
- Create a thumbnail grid:python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
- Read and carefully inspect the thumbnail images:
  - Text truncation: Text is truncated by the title bar, shapes, or slide edges
  - Text overlap: Text overlaps with other text or shapes
  - Positioning issues: Content is too close to slide boundaries or other elements
  - Contrast issues: Insufficient contrast between text and background
- If issues are found, adjust HTML margins/spacing/colors and regenerate the presentation
- Repeat until all slides are visually correct

Edit an existing PowerPoint presentation

When editing slides in an existing PowerPoint presentation, you need to use the original Office Open XML (OOXML) format. This involves unzipping the .pptx file, editing the XML content, and then repackaging it.

Workflow

Must - read the entire file completely: Read ooxml.md(about 500 lines) in full, from beginning to end.Never set any range limits when reading this file. Before editing any presentation, read the full file content to get detailed guidance on the OOXML structure and editing workflow.
Unzip the presentation:python ooxml/scripts/unpack.py <office_file> <output_dir>
Edit the XML files (mainly ppt/slides/slide{N}.xml and related files)
Key: Validate immediately after each edit, and fix any validation errors before continuing:python ooxml/scripts/validate.py <dir> --original <file>
Package the final presentation:python ooxml/scripts/pack.py <input_directory> <office_file>

Create a new PowerPoint presentation using a template

When you need to create a presentation that follows an existing template design, you need to copy and rearrange template slides, then replace the placeholder content.

Workflow

Extract template text and create a visual thumbnail grid：
- Extract text:python -m markitdown template.pptx > template-content.md
- Read template-content.md: Read the entire file to understand the content of the template presentation.Never set any range limits when reading this file.
- Create a thumbnail grid:python scripts/thumbnail.py template.pptx
- For more details, seeCreate thumbnail gridPart
Analyze the template and save the inventory to a file：
- Visual analysis: View the thumbnail grid to understand slide layouts, design patterns, and visual structure
- Create and save the template inventory file to template-inventory.md, including:
```
# 模板清单分析
**总幻灯片数：[count]**
**重要：幻灯片从 0 开始索引（第一张幻灯片 = 0，最后一张幻灯片 = count-1）**

## [类别名称]
- 幻灯片 0：[版式代码（如有）] - 描述/用途
- 幻灯片 1：[版式代码] - 描述/用途
- 幻灯片 2：[版式代码] - 描述/用途
[... 每个幻灯片都必须单独列出其索引 ...]
```
- Use the thumbnail grid: Refer to the visual thumbnails to identify:
  - Layout patterns (title slides, content layouts, section dividers)
  - Image placeholder positions and counts
  - Design consistency across slide groups
  - Visual hierarchy and structure
- This inventory file is required for selecting the appropriate template in the next step
Create a presentation outline based on the template inventory：
- Review the available templates in step 2.
- Select an introduction or title template for the first slide. This should be one of the first templates.
- Select safe, text-based layouts for the other slides.
- Key: Match the layout structure to the actual content：
  - Single-column layout: Use for a unified narrative or a single topic
  - Two-column layout: Use only when you have exactly 2 distinct items/concepts
  - Three-column layout: Use only when you have exactly 3 distinct items/concepts
  - Image + text layout: Use only when you have actual images to insert
  - Quote layout: Use only for actual person quotes (with attribution), never for emphasis
  - Never use a layout with more placeholders than content
  - If you have 2 items, do not force them into a 3-column layout
  - If you have 4+ items, consider splitting them across multiple slides or using a list format
- Count your actual content before selecting a layout
- Verify that every placeholder in the selected layout will be filled with meaningful content
- Select a representative for each content sectionbestlayout option.
- Save outline.md, including the content and the template mapping that leverages the available designs
- Example template mapping:
```
# 要使用的模板幻灯片（0 基索引）
# 警告：验证索引在范围内！有 73 张幻灯片的模板索引为 0-72
# 映射：大纲中的幻灯片编号 -> 模板幻灯片索引
template_mapping = [
    0,   # 使用幻灯片 0（标题/封面）
    34,  # 使用幻灯片 34（B1：标题和正文）
    34,  # 再次使用幻灯片 34（复制用于第二个 B1）
    50,  # 使用幻灯片 50（E1：引用）
    54,  # 使用幻灯片 54（F2：结束语+文本）
]
```
Use rearrange.py to copy, reorder, and delete slides：
- Use the scripts/rearrange.py script to create a new presentation with slides in the desired order:
```
python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
```
- The script automatically handles copying duplicate slides, deleting unused slides, and reordering
- Slide indices start at 0 (the first slide is 0, the second is 1, and so on)
- The same slide index can appear multiple times to duplicate that slide

Use the inventory.py script to extract all text：

Run inventory extraction：

python scripts/inventory.py working.pptx text-inventory.json

Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties.Never set any range limits when reading this file.

Inventory JSON structure:

  {
    "slide-0": {
      "shape-0": {
        "placeholder_type": "TITLE",  // 或非占位符为 null
        "left": 1.5,                  // 位置（英寸）
        "top": 2.0,
        "width": 7.5,
        "height": 1.2,
        "paragraphs": [
          {
            "text": "段落文本",
            // 可选属性（仅在非默认时包含）：
            "bullet": true,           // 检测到显式项目符号
            "level": 0,               // 仅在 bullet 为 true 时包含
            "alignment": "CENTER",    // CENTER、RIGHT（非 LEFT）
            "space_before": 10.0,     // 段前间距（磅）
            "space_after": 6.0,       // 段后间距（磅）
            "line_spacing": 22.4,     // 行间距（磅）
            "font_name": "Arial",     // 来自第一个运行
            "font_size": 14.0,        // 磅
            "bold": true,
            "italic": false,
            "underline": false,
            "color": "FF0000"         // RGB 颜色
          }
        ]
      }
    }
  }

Key features:
- Slides: Named "slide-0", "slide-1", etc.
- Shape: Sorted by visual position (top to bottom, left to right) as "shape-0", "shape-1", etc.
- Placeholder type: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
- Default font size: Extracted from the layout placeholder default_font_size(points, if available)
- Slide numbers are filtered: Shapes with the SLIDE_NUMBER placeholder type are automatically excluded from the inventory
- Bullet: When bullet: true ,level is always included (even if 0)
- Spacing：space_before、space_after and line_spacing(points, included only when set)
- Color: RGB color(e.g., "FF0000"), theme color theme_color(e.g., "DARK_1")
- Properties: Only non-default values are included in the output

Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:
- Key: First verify which shapes exist in the inventory - only reference shapes that actually exist
- Validation: The replace.py script will validate that all shapes in the replacement JSON exist in the inventory
  - If you reference a nonexistent shape, you will receive an error showing the available shapes
  - If you reference a nonexistent slide, you will receive an error indicating that the slide does not exist
  - All validation errors are displayed at once before the script exits
- Important: The replace.py script internally uses inventory.py to identify all text shapes
- Automatic clearing: All text shapes in the inventory will be cleared unless you provide "paragraphs" for them
- Add a "paragraphs" field (not "replacement_paragraphs") for shapes that need content
- Shapes without "paragraphs" in the replacement JSON will automatically have their text cleared
- Paragraphs with bullets will automatically be left-aligned. When "bullet": true , do not set the alignment property
- Generate appropriate replacement content for the placeholder text
- Use the shape size to determine the appropriate content length
- Key: Include the paragraph properties from the original inventory - do not provide only text
- Important: When bullet: true, do not include bullet symbols (•, -, *) in the text - they are added automatically
- Basic formatting rules：
  - Titles should usually have "bold": true
  - List items should have "bullet": true, "level": 0(level is required when bullet is true)
  - Preserve any alignment properties (e.g., for centered text "alignment": "CENTER"）
  - Include font properties when different from the default (e.g., "font_size": 14.0、"font_name": "Lora"）
  - Color: for RGB use "color": "FF0000", theme colors use "theme_color": "DARK_1"
  - The replacement script expectscorrectly formatted paragraphs, not just text strings
  - Overlapping shapes: prefer shapes with a larger default_font_size or a more appropriate placeholder_type
- Save the updated inventory with replacements to replacement-text.json
- Warning: different template layouts have different numbers of shapes - always check the actual inventory before creating replacements
Example of a correctly formatted paragraphs field:
```
"paragraphs": [
  {
    "text": "新演示文稿标题文本",
    "alignment": "CENTER",
    "bold": true
  },
  {
    "text": "章节标题",
    "bold": true
  },
  {
    "text": "第一个要点，不带项目符号符号",
    "bullet": true,
    "level": 0
  },
  {
    "text": "红色文本",
    "color": "FF0000"
  },
  {
    "text": "主题颜色文本",
    "theme_color": "DARK_1"
  },
  {
    "text": "没有特殊格式的普通段落文本"
  }
]
```
Shapes not listed in the replacement JSON will be automatically cleared：
```
{
  "slide-0": {
    "shape-0": {
      "paragraphs": [...] // 此形状获得新文本
    }
    // 清单中的 shape-1 和 shape-2 将自动清除
  }
}
```
Common formatting patterns for presentations：
- Title slide: bold text, sometimes centered
- Section titles within slides: bold text
- Bulleted lists: each item requires "bullet": true, "level": 0
- Body text: usually no special attributes needed
- Quotes: may have special alignment or font attributes
Use replace.py script to apply replacements
```
python scripts/replace.py working.pptx replacement-text.json output.pptx
```
The script will:
- First use inventory.py's function to extract an inventory of all text shapes
- Verify that all shapes in the replacement JSON exist in the inventory
- Clear the text of all shapes identified in the inventory
- Apply new text only to shapes with "paragraphs" defined in the replacement JSON
- Preserve formatting by applying the paragraph attributes from the JSON
- Automatically handle bullets, alignment, font attributes, and colors
- Save the updated presentation
Example validation error:
```
错误：替换 JSON 中的无效形状：
  - 'slide-0' 上未找到形状 'shape-99'。可用形状：shape-0、shape-1、shape-4
  - 清单中未找到幻灯片 'slide-999'
```
```
错误：替换文本使以下形状的溢出更严重：
  - slide-0/shape-2：溢出加剧 1.25"（原为 0.00"，现为 1.25"）
```

Create a thumbnail grid

To create a visual thumbnail grid of PowerPoint slides for quick analysis and reference:

python scripts/thumbnail.py template.pptx [output_prefix]

Features：

Create:thumbnails.jpg(or for large presentations, thumbnails-1.jpg、thumbnails-2.jpg , etc.)
Default: 5 columns, up to 30 slides per grid (5×6)
Custom prefix:python scripts/thumbnail.py template.pptx my-grid
- Note: if you want to output to a specific directory, the output prefix should include the path (e.g. workspace/my-grid）
Adjust the number of columns:--cols 4(range: 3-6, affects the number of slides per grid)
Grid limits: 3 columns = 12 slides/grid, 4 columns = 20, 5 columns = 30, 6 columns = 42
Slides are indexed starting from zero (slide 0, slide 1, etc.)

Use cases：

Template analysis: quickly understand slide layouts and design patterns
Content review: visual overview of the entire presentation
Navigation reference: find specific slides by appearance
Quality check: verify that all slides are formatted correctly

Example：

# 基本用法
python scripts/thumbnail.py presentation.pptx

# 组合选项：自定义名称、列数
python scripts/thumbnail.py template.pptx analysis --cols 4

Convert slides to images

To visually analyze PowerPoint slides, use a two-step process to convert them to images:

Convert PPTX to PDF：

soffice --headless --convert-to pdf template.pptx

Convert PDF pages to JPEG images：
```
pdftoppm -jpeg -r 150 template.pdf slide
```
This creates slide-1.jpg、slide-2.jpg and other files.

Options:

-r 150: set the resolution to 150 DPI (adjust to balance quality/size)
-jpeg: output JPEG format (if needed, use -png Output PNG)
-f N: the first page to convert (e.g. -f 2 start from page 2)
-l N: the last page to convert (e.g. -l 5 stop at page 5)
slide: prefix of the output file

Specific range example:

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # 仅转换第 2-5 页

Code Style Guide

Important: When generating PPTX operation code:

Write concise code
Avoid lengthy variable names and redundant operations
Avoid unnecessary print statements

Dependencies

Required dependencies (should already be installed):

markitdown：pip install "markitdown[pptx]"(used to extract text from presentations)
pptxgenjs：npm install -g pptxgenjs(used to create presentations via html2pptx)
playwright：npm install -g playwright(used for HTML rendering in html2pptx)
react-icons：npm install -g react-icons react react-dom(used for icons)
sharp：npm install -g sharp(used for SVG rasterization and image processing)
LibreOffice：sudo apt-get install libreoffice(used for PDF conversion)
Poppler：sudo apt-get install poppler-utils(used for converting PDF to images with pdftoppm)
defusedxml：pip install defusedxml(used for secure XML parsing)

About this skill

Overview

Reading and analyzing content

Text extraction

Raw XML access

Unzip the file

Key file structure

Typography and color extraction

Creating a new PowerPoint presentation without using a template

Design principles

Color Palette Selection

Visual Detail Options

Layout Tips

Workflow

Edit an existing PowerPoint presentation

Workflow

Create a new PowerPoint presentation using a template

Workflow

Create a thumbnail grid

Convert slides to images

Code Style Guide

Dependencies