presentation-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PPTX creation, editing, and analysis

PPTX 创建、编辑与分析

Overview

概述

A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
用户可能会要求你创建、编辑或分析.pptx文件的内容。.pptx文件本质上是一个包含XML文件和其他资源的ZIP压缩包,你可以读取或编辑这些内容。针对不同的任务,你可以使用不同的工具和工作流。

Reading and analyzing content

读取与分析内容

Text extraction

文本提取

If you just need to read the text contents of a presentation, you should convert the document to markdown:
bash
undefined
如果你只需要读取演示文稿的文本内容,应将文档转换为Markdown格式:
bash
undefined

Convert document to markdown

Convert document to markdown

python -m markitdown path-to-file.pptx
undefined
python -m markitdown path-to-file.pptx
undefined

Raw XML access

原始XML访问

You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.
如需处理以下内容,你需要访问原始XML:批注、演讲者备注、幻灯片布局、动画、设计元素以及复杂格式。针对这些功能,你需要解压演示文稿并读取其原始XML内容。

Unpacking a file

解压文件

python ooxml/scripts/unpack.py <office_file> <output_dir>
Note: The unpack.py script is located at
skills/presentation-builder/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.
python ooxml/scripts/unpack.py <office_file> <output_dir>
注意:unpack.py脚本位于项目根目录下的
skills/presentation-builder/ooxml/scripts/unpack.py
路径。如果该脚本不在此路径,使用
find . -name "unpack.py"
命令查找。

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
  • ppt/presentation.xml
    - 演示文稿主元数据和幻灯片引用
  • ppt/slides/slide{N}.xml
    - 单个幻灯片内容(如slide1.xml、slide2.xml等)
  • ppt/notesSlides/notesSlide{N}.xml
    - 每张幻灯片的演讲者备注
  • ppt/comments/modernComment_*.xml
    - 特定幻灯片的批注
  • ppt/slideLayouts/
    - 幻灯片布局模板
  • ppt/slideMasters/
    - 幻灯片母版模板
  • ppt/theme/
    - 主题和样式信息
  • ppt/media/
    - 图片和其他媒体文件

Typography and color extraction

排版与颜色提取

When given an example design to emulate: Always 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
当需要模仿示例设计时:务必先通过以下方法分析演示文稿的排版和颜色:
  1. 读取主题文件:查看
    ppt/theme/theme1.xml
    中的颜色(
    <a:clrScheme>
    )和字体(
    <a:fontScheme>
  2. 示例幻灯片内容:检查
    ppt/slides/slide1.xml
    中的实际字体使用(
    <a:rPr>
    )和颜色
  3. 搜索模式:使用grep命令在所有XML文件中查找颜色(
    <a:solidFill>
    <a:srgbClr>
    )和字体引用

Creating a new PowerPoint presentation without a template

无模板创建新PowerPoint演示文稿

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.
从头创建新PowerPoint演示文稿时,使用html2pptx工作流将HTML幻灯片转换为格式精准的PowerPoint文件。

Design Principles

设计原则

CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:
  1. Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
  2. Check for branding: If the user mentions a company/organization, consider their brand colors and identity
  3. Match palette to content: Select colors that reflect the subject
  4. State your approach: Explain your design choices before writing code
Requirements:
  • ✅ State your content-informed design approach BEFORE writing code
  • ✅ Use web-safe fonts only: 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
  • ✅ Be consistent: repeat patterns, spacing, and visual language across slides
关键要求:在创建任何演示文稿之前,先分析内容并选择合适的设计元素:
  1. 考虑主题内容:该演示文稿的主题是什么?它需要呈现何种基调、行业或氛围?
  2. 检查品牌规范:如果用户提及公司或组织,需考虑其品牌颜色和标识
  3. 配色与内容匹配:选择能体现主题的颜色
  4. 说明设计思路:在编写代码前,先解释你的设计选择
要求
  • ✅ 在编写代码前,务必说明基于内容的设计思路
  • ✅ 仅使用网页安全字体:Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
  • ✅ 通过字号、字重和颜色构建清晰的视觉层级
  • ✅ 确保可读性:高对比度、合适的字号、整洁的对齐方式
  • ✅ 保持一致性:在所有幻灯片中重复使用相同的布局模式、间距和视觉语言

Color Palette Selection

配色方案选择

Choosing colors creatively:
  • Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
  • Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
  • Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
  • Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
  • Ensure contrast: Text must be clearly readable on backgrounds
Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):
  1. Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
  2. Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
  3. Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
  4. Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
  5. Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
  6. Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
  7. Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
  8. Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
  9. Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
  10. Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
  11. Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
  12. Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
  13. Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
  14. Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
  15. Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
  16. Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
  17. Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
  18. Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)
创意配色技巧
  • 超越默认选项:选择真正匹配主题的颜色,避免机械选择
  • 多角度考量:主题、行业、氛围、活力水平、目标受众、品牌标识(如有提及)
  • 勇于尝试:尝试意想不到的组合——医疗行业演示文稿不一定非要用绿色,金融行业也不一定非要用深蓝色
  • 构建配色方案:选择3-5种协调的颜色(主色+辅助色+强调色)
  • 确保对比度:文本在背景上必须清晰可读
示例配色方案(用于激发创意——可选择其一、调整或自行创建):
  1. 经典蓝:深藏青(#1C2833)、石板灰(#2E4053)、银灰(#AAB7B8)、米白(#F4F6F6)
  2. 蓝绿与珊瑚橙:蓝绿(#5EA8A7)、深蓝绿(#277884)、珊瑚橙(#FE4447)、白色(#FFFFFF)
  3. 醒目红:深红(#C0392B)、亮红(#E74C3C)、橙色(#F39C12)、黄色(#F1C40F)、绿色(#2ECC71)
  4. 暖粉棕:淡紫棕(#A49393)、腮红粉(#EED6D3)、玫瑰粉(#E8B4B8)、奶油白(#FAF7F2)
  5. 勃艮第奢华风:勃艮第红(#5D1D2E)、深红(#951233)、铁锈橙(#C15937)、金色(#997929)
  6. 深紫与祖母绿:紫色(#B165FB)、深蓝色(#181B24)、祖母绿(#40695B)、白色(#FFFFFF)
  7. 奶油白与森林绿:奶油白(#FFE1C7)、森林绿(#40695B)、白色(#FCFCFC)
  8. 粉紫撞色:粉色(#F8275B)、珊瑚橙(#FF574A)、玫瑰红(#FF737D)、紫色(#3D2F68)
  9. 石灰绿与李子紫:石灰绿(#C5DE82)、李子紫(#7C3A5F)、珊瑚橙(#FD8C6E)、蓝灰(#98ACB5)
  10. 黑金风格:金色(#BF9A4A)、黑色(#000000)、奶油白(#F4F6F6)
  11. 鼠尾草绿与赤陶色:鼠尾草绿(#87A96B)、赤陶色(#E07A5F)、奶油白(#F4F1DE)、炭灰(#2C2C2C)
  12. 炭灰与红:炭灰(#292929)、红色(#E33737)、浅灰(#CCCBCB)
  13. 活力橙:橙色(#F96D00)、浅灰(#F2F2F2)、炭灰(#222831)
  14. 森林绿:黑色(#191A19)、绿色(#4E9F3D)、深绿(#1E5128)、白色(#FFFFFF)
  15. 复古彩虹:紫色(#722880)、粉色(#D72D51)、橙色(#EB5C18)、琥珀色(#F08800)、金色(#DEB600)
  16. 复古大地色:芥末黄(#E3B448)、鼠尾草绿(#CBD18F)、森林绿(#3A6B35)、奶油白(#F4F1DE)
  17. 海岸玫瑰色:旧玫瑰色(#AD7670)、海狸棕(#B49886)、蛋壳白(#F3ECDC)、烟灰绿(#BFD5BE)
  18. 橙与绿松石:浅橙(#FC993E)、灰绿松石(#667C6F)、白色(#FCFCFC)

Visual Details Options

视觉细节选项

Geometric Patterns:
  • Diagonal section dividers instead of horizontal
  • Asymmetric column widths (30/70, 40/60, 25/75)
  • Rotated text headers at 90° or 270°
  • Circular/hexagonal frames for images
  • Triangular accent shapes in corners
  • Overlapping shapes for depth
Border & Frame Treatments:
  • Thick single-color borders (10-20pt) on one side only
  • Double-line borders with contrasting colors
  • Corner brackets instead of full frames
  • L-shaped borders (top+left or bottom+right)
  • Underline accents beneath headers (3-5pt thick)
Typography Treatments:
  • Extreme size contrast (72pt headlines vs 11pt body)
  • All-caps headers with wide letter spacing
  • Numbered sections in oversized display type
  • Monospace (Courier New) for data/stats/technical content
  • Condensed fonts (Arial Narrow) for dense information
  • Outlined text for emphasis
Chart & Data Styling:
  • Monochrome charts with single accent color for key data
  • Horizontal bar charts instead of vertical
  • Dot plots instead of bar charts
  • Minimal gridlines or none at all
  • Data labels directly on elements (no legends)
  • Oversized numbers for key metrics
Layout Innovations:
  • Full-bleed images with text overlays
  • Sidebar column (20-30% width) for navigation/context
  • Modular grid systems (3×3, 4×4 blocks)
  • Z-pattern or F-pattern content flow
  • Floating text boxes over colored shapes
  • Magazine-style multi-column layouts
Background Treatments:
  • Solid color blocks occupying 40-60% of slide
  • Gradient fills (vertical or diagonal only)
  • Split backgrounds (two colors, diagonal or vertical)
  • Edge-to-edge color bands
  • Negative space as a design element
几何图案:
  • 用对角分割线替代水平分割线
  • 非对称列宽(30/70、40/60、25/75)
  • 标题文本旋转90°或270°
  • 图片使用圆形/六边形边框
  • 角落添加三角形装饰形状
  • 重叠形状增加层次感
边框与框架处理:
  • 仅在单侧添加粗单色边框(10-20pt)
  • 双色双线边框
  • 用角落括号替代完整框架
  • L型边框(上+左或下+右)
  • 标题下方添加下划线装饰(3-5pt粗)
排版处理:
  • 极端字号对比(72pt标题 vs 11pt正文)
  • 标题使用全大写并加宽字间距
  • 章节编号使用超大显示字体
  • 数据/统计/技术内容使用等宽字体(Courier New)
  • 密集信息使用窄体字体(Arial Narrow)
  • 文本描边强调
图表与数据样式:
  • 单色图表,仅关键数据使用强调色
  • 用水平条形图替代垂直条形图
  • 用点图替代条形图
  • 极简网格线或无网格线
  • 数据标签直接标注在元素上(无图例)
  • 关键指标使用超大字号
布局创新:
  • 全屏图片叠加文本
  • 侧边栏(宽度20-30%)用于导航/上下文说明
  • 模块化网格系统(3×3、4×4区块)
  • Z型或F型内容流
  • 彩色形状上悬浮文本框
  • 杂志风格多栏布局
背景处理:
  • 纯色块占幻灯片40-60%
  • 渐变填充(仅垂直或对角)
  • 分割背景(两种颜色,对角或垂直)
  • 通栏色带
  • 留白作为设计元素

Layout Tips

布局技巧

When creating slides with charts or tables:
  • Two-column layout (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
  • Full-slide layout: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
  • NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues
创建包含图表或表格的幻灯片时:
  • 优先使用双列布局:标题跨满宽度,下方分为两列——一列放文本/项目符号,另一列放核心内容。这种布局平衡性更好,能提升图表/表格的可读性。使用不等宽的flexbox布局(如40%/60%分割),为不同类型的内容优化空间。
  • 全屏布局:让核心内容(图表/表格)占满整个幻灯片,以最大化视觉冲击力和可读性
  • 绝对不要垂直堆叠:不要在单列中将图表/表格放在文本下方——这会导致可读性差和布局问题

Workflow

工作流

  1. MANDATORY - READ ENTIRE FILE: 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. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
    • Use
      <p>
      ,
      <h1>
      -
      <h6>
      ,
      <ul>
      ,
      <ol>
      for all text content
    • Use
      class="placeholder"
      for areas where charts/tables will be added (render with gray background for visibility)
    • CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
    • LAYOUT: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
  3. Create and run a JavaScript file using the
    html2pptx.js
    library to convert HTML slides to PowerPoint and save the presentation
    • 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()
  4. 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
  1. 强制要求 - 完整阅读文件:完整阅读
    html2pptx.md
    全文。阅读此文件时绝对不要设置范围限制。在开始创建演示文稿前,通读全文以了解详细语法、关键格式规则和最佳实践。
  2. 为每张幻灯片创建HTML文件,设置正确尺寸(如16:9比例使用720pt × 405pt)
    • 使用
      <p>
      <h1>
      -
      <h6>
      <ul>
      <ol>
      标记所有文本内容
    • 为将添加图表/表格的区域添加
      class="placeholder"
      类(渲染为灰色背景以提高可见性)
    • 关键要求:先使用Sharp将渐变和图标栅格化为PNG图片,再在HTML中引用
    • 布局:包含图表/表格/图片的幻灯片,优先使用全屏布局或双列布局以提升可读性
  3. 创建并运行JavaScript文件,使用
    html2pptx.js
    库将HTML幻灯片转换为PowerPoint并保存
    • 使用
      html2pptx()
      函数处理每个HTML文件
    • 使用PptxGenJS API将图表和表格添加到占位区域
    • 使用
      pptx.writeFile()
      保存演示文稿
  4. 视觉验证:生成缩略图并检查布局问题
    • 创建缩略图网格:
      python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
    • 仔细检查缩略图,查看以下问题:
      • 文本截断:文本被标题栏、形状或幻灯片边缘截断
      • 文本重叠:文本与其他文本或形状重叠
      • 定位问题:内容过于靠近幻灯片边界或其他元素
      • 对比度问题:文本与背景对比度不足
    • 若发现问题,调整HTML的边距/间距/颜色并重新生成演示文稿
    • 重复此过程直到所有幻灯片视觉效果正确

Editing an existing PowerPoint presentation

编辑现有PowerPoint演示文稿

When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.
编辑现有PowerPoint演示文稿的幻灯片时,需要使用原始Office Open XML (OOXML)格式。流程包括解压.pptx文件、编辑XML内容,然后重新打包。

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>
  1. 强制要求 - 完整阅读文件:完整阅读
    ooxml.md
    (约500行)全文。阅读此文件时绝对不要设置范围限制。在开始编辑演示文稿前,通读全文以了解OOXML结构和编辑工作流的详细指南。
  2. 解压演示文稿:
    python ooxml/scripts/unpack.py <office_file> <output_dir>
  3. 编辑XML文件(主要是
    ppt/slides/slide{N}.xml
    及相关文件)
  4. 关键要求:每次编辑后立即验证,修复所有验证错误后再继续:
    python ooxml/scripts/validate.py <dir> --original <file>
  5. 重新打包最终演示文稿:
    python ooxml/scripts/pack.py <input_directory> <office_file>

Creating a new PowerPoint presentation using a template

使用模板创建新PowerPoint演示文稿

When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.
当需要创建遵循现有模板设计的演示文稿时,你需要复制并重新排列模板幻灯片,然后替换占位符内容。

Workflow

工作流

  1. Extract template text AND create visual thumbnail grid:
    • Extract text:
      python -m markitdown template.pptx > template-content.md
    • Read
      template-content.md
      : Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
    • Create thumbnail grids:
      python scripts/thumbnail.py template.pptx
    • See Creating Thumbnail Grids section for more details
  2. Analyze template and save inventory to a file:
    • Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
    • Create and save a template inventory file at
      template-inventory.md
      containing:
      markdown
      # Template Inventory Analysis
      **Total Slides: [count]**
      **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
      
      ## [Category Name]
      - Slide 0: [Layout code if available] - Description/purpose
      - Slide 1: [Layout code] - Description/purpose
      - Slide 2: [Layout code] - Description/purpose
      [... EVERY slide must be listed individually with its index ...]
    • Using the thumbnail grid: Reference the visual thumbnails to identify:
      • Layout patterns (title slides, content layouts, section dividers)
      • Image placeholder locations and counts
      • Design consistency across slide groups
      • Visual hierarchy and structure
    • This inventory file is REQUIRED for selecting appropriate templates in the next step
  3. Create presentation outline based on template inventory:
    • Review available templates from step 2.
    • Choose an intro or title template for the first slide. This should be one of the first templates.
    • Choose safe, text-based layouts for the other slides.
    • CRITICAL: Match layout structure to actual content:
      • Single-column layouts: Use for unified narrative or single topic
      • Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
      • Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
      • Image + text layouts: Use ONLY when you have actual images to insert
      • Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
      • Never use layouts with more placeholders than you have content
      • If you have 2 items, don't force them into a 3-column layout
      • If you have 4+ items, consider breaking into multiple slides or using a list format
    • Count your actual content pieces BEFORE selecting the layout
    • Verify each placeholder in the chosen layout will be filled with meaningful content
    • Select one option representing the best layout for each content section.
    • Save
      outline.md
      with content AND template mapping that leverages available designs
    • Example template mapping:
      # Template slides to use (0-based indexing)
      # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
      # Mapping: slide numbers from outline -> template slide indices
      template_mapping = [
          0,   # Use slide 0 (Title/Cover)
          34,  # Use slide 34 (B1: Title and body)
          34,  # Use slide 34 again (duplicate for second B1)
          50,  # Use slide 50 (E1: Quote)
          54,  # Use slide 54 (F2: Closing + Text)
      ]
  4. Duplicate, reorder, and delete slides using
    rearrange.py
    :
    • Use the
      scripts/rearrange.py
      script to create a new presentation with slides in the desired order:
      bash
      python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
    • The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
    • Slide indices are 0-based (first slide is 0, second is 1, etc.)
    • The same slide index can appear multiple times to duplicate that slide
  5. Extract ALL text using the
    inventory.py
    script
    :
    • Run inventory extraction:
      bash
      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.
    • The inventory JSON structure:
      json
        {
          "slide-0": {
            "shape-0": {
              "placeholder_type": "TITLE",  // or null for non-placeholders
              "left": 1.5,                  // position in inches
              "top": 2.0,
              "width": 7.5,
              "height": 1.2,
              "paragraphs": [
                {
                  "text": "Paragraph text",
                  // Optional properties (only included when non-default):
                  "bullet": true,           // explicit bullet detected
                  "level": 0,               // only included when bullet is true
                  "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
                  "space_before": 10.0,     // space before paragraph in points
                  "space_after": 6.0,       // space after paragraph in points
                  "line_spacing": 22.4,     // line spacing in points
                  "font_name": "Arial",     // from first run
                  "font_size": 14.0,        // in points
                  "bold": true,
                  "italic": false,
                  "underline": false,
                  "color": "FF0000"         // RGB color
                }
              ]
            }
          }
        }
    • Key features:
      • Slides: Named as "slide-0", "slide-1", etc.
      • Shapes: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
      • Placeholder types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
      • Default font size:
        default_font_size
        in points extracted from layout placeholders (when available)
      • Slide numbers are filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
      • Bullets: When
        bullet: true
        ,
        level
        is always included (even if 0)
      • Spacing:
        space_before
        ,
        space_after
        , and
        line_spacing
        in points (only included when set)
      • Colors:
        color
        for RGB (e.g., "FF0000"),
        theme_color
        for theme colors (e.g., "DARK_1")
      • Properties: Only non-default values are included in the output
  6. Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:
    • CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
    • VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
      • If you reference a non-existent shape, you'll get an error showing available shapes
      • If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
      • All validation errors are shown at once before the script exits
    • IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
    • AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
    • Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
    • Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
    • Paragraphs with bullets will be automatically left aligned. Don't set the
      alignment
      property on when
      "bullet": true
    • Generate appropriate replacement content for placeholder text
    • Use shape size to determine appropriate content length
    • CRITICAL: Include paragraph properties from the original inventory - don't just provide text
    • IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
    • ESSENTIAL FORMATTING RULES:
      • Headers/titles should typically have
        "bold": true
      • List items should have
        "bullet": true, "level": 0
        (level is required when bullet is true)
      • Preserve any alignment properties (e.g.,
        "alignment": "CENTER"
        for centered text)
      • Include font properties when different from default (e.g.,
        "font_size": 14.0
        ,
        "font_name": "Lora"
        )
      • Colors: Use
        "color": "FF0000"
        for RGB or
        "theme_color": "DARK_1"
        for theme colors
      • The replacement script expects properly formatted paragraphs, not just text strings
      • Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
    • Save the updated inventory with replacements to
      replacement-text.json
    • WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements
    Example paragraphs field showing proper formatting:
    json
    "paragraphs": [
      {
        "text": "New presentation title text",
        "alignment": "CENTER",
        "bold": true
      },
      {
        "text": "Section Header",
        "bold": true
      },
      {
        "text": "First bullet point without bullet symbol",
        "bullet": true,
        "level": 0
      },
      {
        "text": "Red colored text",
        "color": "FF0000"
      },
      {
        "text": "Theme colored text",
        "theme_color": "DARK_1"
      },
      {
        "text": "Regular paragraph text without special formatting"
      }
    ]
    Shapes not listed in the replacement JSON are automatically cleared:
    json
    {
      "slide-0": {
        "shape-0": {
          "paragraphs": [...] // This shape gets new text
        }
        // shape-1 and shape-2 from inventory will be cleared automatically
      }
    }
    Common formatting patterns for presentations:
    • Title slides: Bold text, sometimes centered
    • Section headers within slides: Bold text
    • Bullet lists: Each item needs
      "bullet": true, "level": 0
    • Body text: Usually no special properties needed
    • Quotes: May have special alignment or font properties
  7. Apply replacements using the
    replace.py
    script
    bash
    python scripts/replace.py working.pptx replacement-text.json output.pptx
    The script will:
    • First extract the inventory of ALL text shapes using functions from inventory.py
    • Validate that all shapes in the replacement JSON exist in the inventory
    • Clear text from ALL shapes identified in the inventory
    • Apply new text only to shapes with "paragraphs" defined in the replacement JSON
    • Preserve formatting by applying paragraph properties from the JSON
    • Handle bullets, alignment, font properties, and colors automatically
    • Save the updated presentation
    Example validation errors:
    ERROR: Invalid shapes in replacement JSON:
      - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
      - Slide 'slide-999' not found in inventory
    ERROR: Replacement text made overflow worse in these shapes:
      - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
  1. 提取模板文本并创建视觉缩略图网格:
    • 提取文本:
      python -m markitdown template.pptx > template-content.md
    • 阅读
      template-content.md
      :完整阅读文件以了解模板演示文稿的内容。阅读此文件时绝对不要设置范围限制
    • 创建缩略图网格:
      python scripts/thumbnail.py template.pptx
    • 更多细节请查看创建缩略图网格部分
  2. 分析模板并将清单保存到文件:
    • 视觉分析:查看缩略图网格以了解幻灯片布局、设计模式和视觉结构
    • 创建并保存模板清单文件
      template-inventory.md
      ,内容如下:
      markdown
      # 模板清单分析
      **总幻灯片数: [数量]**
      **重要提示:幻灯片为0索引(第一张幻灯片=0,最后一张=数量-1)**
      
      ## [类别名称]
      - 幻灯片0: [布局代码(如有)] - 描述/用途
      - 幻灯片1: [布局代码] - 描述/用途
      - 幻灯片2: [布局代码] - 描述/用途
      [... 必须逐个列出所有幻灯片及其索引 ...]
    • 使用缩略图网格:参考视觉缩略图识别以下内容:
      • 布局模式(标题幻灯片、内容布局、章节分隔页)
      • 图片占位符的位置和数量
      • 幻灯片组之间的设计一致性
      • 视觉层级和结构
    • 此清单文件是下一步选择合适模板的必需文件
  3. 基于模板清单创建演示文稿大纲:
    • 查看步骤2中的可用模板
    • 为第一张幻灯片选择介绍或标题模板,应选择模板中的前几个幻灯片之一
    • 为其他幻灯片选择安全的纯文本布局
    • 关键要求:布局结构与实际内容匹配:
      • 单列布局:用于统一叙事或单一主题
      • 双列布局:仅当你有恰好2个不同的项目/概念时使用
      • 三列布局:仅当你有恰好3个不同的项目/概念时使用
      • 图片+文本布局:仅当你有实际图片要插入时使用
      • 引用布局:仅用于真实的名人名言(需注明出处),不要用于强调
      • 不要使用占位符数量多于内容数量的布局
      • 如果你有2个项目,不要强行使用三列布局
      • 如果你有4个及以上项目,考虑拆分为多张幻灯片或使用列表格式
    • 在选择布局前,先统计实际内容的数量
    • 验证所选布局中的每个占位符都将填充有意义的内容
    • 为每个内容部分选择最佳布局选项
    • 保存
      outline.md
      ,包含内容和模板映射,充分利用现有设计
    • 模板映射示例:
      # 要使用的模板幻灯片(0索引)
      # 警告:验证索引是否在范围内!包含73张幻灯片的模板索引为0-72
      # 映射:大纲幻灯片编号 -> 模板幻灯片索引
      template_mapping = [
          0,   # 使用幻灯片0(标题/封面)
          34,  # 使用幻灯片34(B1:标题和正文)
          34,  # 再次使用幻灯片34(复制以创建第二个B1布局)
          50,  # 使用幻灯片50(E1:引用)
          54,  # 使用幻灯片54(F2:结尾+文本)
      ]
  4. 使用
    rearrange.py
    复制、重新排序和删除幻灯片
    :
    • 使用
      scripts/rearrange.py
      脚本创建包含所需顺序幻灯片的新演示文稿:
      bash
      python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
    • 该脚本会自动处理重复幻灯片的复制、未使用幻灯片的删除和重新排序
    • 幻灯片索引为0索引(第一张是0,第二张是1,以此类推)
    • 同一幻灯片索引可多次出现以复制该幻灯片
  5. 使用
    inventory.py
    脚本提取所有文本
    :
    • 运行清单提取:
      bash
      python scripts/inventory.py working.pptx text-inventory.json
    • 阅读text-inventory.json:完整阅读文件以了解所有形状及其属性。阅读此文件时绝对不要设置范围限制
    • 清单JSON结构:
      json
        {
          "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颜色
                }
              ]
            }
          }
        }
    • 主要特性:
      • 幻灯片:命名为"slide-0"、"slide-1"等
      • 形状:按视觉位置(从上到下、从左到右)排序,命名为"shape-0"、"shape-1"等
      • 占位符类型:TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT或null
      • 默认字号:从布局占位符提取的
        default_font_size
        (磅,如有)
      • 幻灯片编号已过滤:占位符类型为SLIDE_NUMBER的形状会自动从清单中排除
      • 项目符号:当
        bullet: true
        时,始终包含
        level
        (即使为0)
      • 间距
        space_before
        space_after
        line_spacing
        以磅为单位(仅在设置时包含)
      • 颜色:RGB颜色使用
        color
        (如"FF0000"),主题颜色使用
        theme_color
        (如"DARK_1")
      • 属性:仅包含非默认值
  6. 生成替换文本并保存到JSON文件 基于上一步的文本清单:
    • 关键要求:首先验证清单中存在哪些形状——仅引用实际存在的形状
    • 验证:replace.py脚本会验证替换JSON中的所有形状是否存在于清单中
      • 如果你引用了不存在的形状,会显示错误并列出可用形状
      • 如果你引用了不存在的幻灯片,会显示错误提示该幻灯片不存在
      • 所有验证错误会在脚本退出前一次性显示
    • 重要提示:replace.py脚本内部使用inventory.py来识别所有文本形状
    • 自动清空:清单中的所有文本形状都会被清空,除非你为其提供"paragraphs"
    • 为需要填充内容的形状添加"paragraphs"字段(不是"replacement_paragraphs")
    • 替换JSON中没有"paragraphs"的形状会被自动清空文本
    • 带项目符号的段落会自动左对齐,
      "bullet": true
      时不要设置
      alignment
      属性
    • 为占位符文本生成合适的替换内容
    • 根据形状大小确定合适的内容长度
    • 关键要求:包含原始清单中的段落属性——不要只提供文本
    • 重要提示:当
      bullet: true
      时,不要在文本中包含项目符号(•、-、*)——会自动添加
    • 核心格式规则:
      • 标题通常应设置
        "bold": true
      • 列表项应设置
        "bullet": true, "level": 0
        bullet
        为true时必须包含
        level
      • 保留对齐属性(如居中文本设置
        "alignment": "CENTER"
      • 与默认值不同时包含字体属性(如
        "font_size": 14.0
        "font_name": "Lora"
      • 颜色:RGB使用
        "color": "FF0000"
        ,主题颜色使用
        "theme_color": "DARK_1"
      • 替换脚本需要格式正确的段落,而不仅仅是文本字符串
      • 重叠形状:优先选择默认字号更大或占位符类型更合适的形状
    • 将包含替换内容的更新清单保存到
      replacement-text.json
    • 警告:不同模板布局的形状数量不同——创建替换内容前务必检查实际清单
    格式正确的paragraphs字段示例:
    json
    "paragraphs": [
      {
        "text": "新演示文稿标题文本",
        "alignment": "CENTER",
        "bold": true
      },
      {
        "text": "章节标题",
        "bold": true
      },
      {
        "text": "第一个项目符号(不要包含项目符号)",
        "bullet": true,
        "level": 0
      },
      {
        "text": "红色文本",
        "color": "FF0000"
      },
      {
        "text": "主题颜色文本",
        "theme_color": "DARK_1"
      },
      {
        "text": "无特殊格式的常规段落文本"
      }
    ]
    替换JSON中未列出的形状会被自动清空:
    json
    {
      "slide-0": {
        "shape-0": {
          "paragraphs": [...] // 此形状会被设置新文本
        }
        // 清单中的shape-1和shape-2会被自动清空
      }
    }
    演示文稿常见格式模式:
    • 标题幻灯片:粗体文本,有时居中
    • 幻灯片内的章节标题:粗体文本
    • 项目符号列表:每个项目需要
      "bullet": true, "level": 0
    • 正文:通常不需要特殊属性
    • 引用:可能有特殊对齐或字体属性
  7. 使用
    replace.py
    脚本应用替换内容
    bash
    python scripts/replace.py working.pptx replacement-text.json output.pptx
    脚本会:
    • 首先使用inventory.py中的函数提取所有文本形状的清单
    • 验证替换JSON中的所有形状是否存在于清单中
    • 清空清单中识别的所有形状的文本
    • 仅对替换JSON中定义了"paragraphs"的形状应用新文本
    • 通过应用JSON中的段落属性保留格式
    • 自动处理项目符号、对齐、字体属性和颜色
    • 保存更新后的演示文稿
    验证错误示例:
    ERROR: 替换JSON中的无效形状:
      - 幻灯片'slide-0'中未找到'shape-99'。可用形状: shape-0, shape-1, shape-4
      - 清单中未找到幻灯片'slide-999'
    ERROR: 以下形状的替换文本溢出情况恶化:
      - slide-0/shape-2: 溢出增加1.25英寸(原0.00英寸,现1.25英寸)

Creating Thumbnail Grids

创建缩略图网格

To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:
bash
python scripts/thumbnail.py template.pptx [output_prefix]
Features:
  • Creates:
    thumbnails.jpg
    (or
    thumbnails-1.jpg
    ,
    thumbnails-2.jpg
    , etc. for large decks)
  • Default: 5 columns, max 30 slides per grid (5×6)
  • Custom prefix:
    python scripts/thumbnail.py template.pptx my-grid
    • Note: The output prefix should include the path if you want output in a specific directory (e.g.,
      workspace/my-grid
      )
  • Adjust columns:
    --cols 4
    (range: 3-6, affects slides per grid)
  • Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
  • Slides are zero-indexed (Slide 0, Slide 1, etc.)
Use cases:
  • Template analysis: Quickly understand slide layouts and design patterns
  • Content review: Visual overview of entire presentation
  • Navigation reference: Find specific slides by their visual appearance
  • Quality check: Verify all slides are properly formatted
Examples:
bash
undefined
要快速分析和参考PowerPoint幻灯片,可创建视觉缩略图网格:
bash
python scripts/thumbnail.py template.pptx [output_prefix]
特性:
  • 生成文件:
    thumbnails.jpg
    (大型演示文稿会生成
    thumbnails-1.jpg
    thumbnails-2.jpg
    等)
  • 默认:5列,每个网格最多30张幻灯片(5×6)
  • 自定义前缀:
    python scripts/thumbnail.py template.pptx my-grid
    • 注意:如果要将输出保存到特定目录,输出前缀应包含路径(如
      workspace/my-grid
  • 调整列数:
    --cols 4
    (范围:3-6,影响每个网格的幻灯片数量)
  • 网格限制:3列=12张/网格,4列=20张,5列=30张,6列=42张
  • 幻灯片为0索引(幻灯片0、幻灯片1等)
使用场景:
  • 模板分析:快速了解幻灯片布局和设计模式
  • 内容审核:演示文稿的视觉概览
  • 导航参考:通过视觉外观查找特定幻灯片
  • 质量检查:验证所有幻灯片格式是否正确
示例:
bash
undefined

Basic usage

基础用法

python scripts/thumbnail.py presentation.pptx
python scripts/thumbnail.py presentation.pptx

Combine options: custom name, columns

组合选项:自定义名称、列数

python scripts/thumbnail.py template.pptx analysis --cols 4
undefined
python scripts/thumbnail.py template.pptx analysis --cols 4
undefined

Converting Slides to Images

将幻灯片转换为图片

To visually analyze PowerPoint slides, convert them to images using a two-step process:
  1. Convert PPTX to PDF:
    bash
    soffice --headless --convert-to pdf template.pptx
  2. Convert PDF pages to JPEG images:
    bash
    pdftoppm -jpeg -r 150 template.pdf slide
    This creates files like
    slide-1.jpg
    ,
    slide-2.jpg
    , etc.
Options:
  • -r 150
    : Sets resolution to 150 DPI (adjust for quality/size balance)
  • -jpeg
    : Output JPEG format (use
    -png
    for PNG if preferred)
  • -f N
    : First page to convert (e.g.,
    -f 2
    starts from page 2)
  • -l N
    : Last page to convert (e.g.,
    -l 5
    stops at page 5)
  • slide
    : Prefix for output files
Example for specific range:
bash
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5
要可视化分析PowerPoint幻灯片,可通过两步将其转换为图片:
  1. 将PPTX转换为PDF:
    bash
    soffice --headless --convert-to pdf template.pptx
  2. 将PDF页面转换为JPEG图片:
    bash
    pdftoppm -jpeg -r 150 template.pdf slide
    这会生成
    slide-1.jpg
    slide-2.jpg
    等文件
选项:
  • -r 150
    : 设置分辨率为150 DPI(可调整以平衡质量和大小)
  • -jpeg
    : 输出JPEG格式(如需PNG可使用
    -png
  • -f N
    : 起始转换页码(如
    -f 2
    从第2页开始)
  • -l N
    : 结束转换页码(如
    -l 5
    到第5页结束)
  • slide
    : 输出文件前缀
特定范围转换示例:
bash
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # 仅转换第2-5页

Code Style Guidelines

代码风格指南

IMPORTANT: When generating code for PPTX operations:
  • Write concise code
  • Avoid verbose variable names and redundant operations
  • Avoid unnecessary print statements
重要提示:生成PPTX操作相关代码时:
  • 编写简洁的代码
  • 避免冗长的变量名和冗余操作
  • 避免不必要的打印语句

Dependencies

依赖项

Required dependencies (should already be installed):
  • markitdown:
    pip install "markitdown[pptx]"
    (for text extraction from presentations)
  • pptxgenjs:
    npm install -g pptxgenjs
    (for creating presentations via html2pptx)
  • playwright:
    npm install -g playwright
    (for HTML rendering in html2pptx)
  • react-icons:
    npm install -g react-icons react react-dom
    (for icons)
  • sharp:
    npm install -g sharp
    (for SVG rasterization and image processing)
  • LibreOffice:
    sudo apt-get install libreoffice
    (for PDF conversion)
  • Poppler:
    sudo apt-get install poppler-utils
    (for pdftoppm to convert PDF to images)
  • defusedxml:
    pip install defusedxml
    (for secure XML parsing)
所需依赖项(应已安装):
  • markitdown:
    pip install "markitdown[pptx]"
    (用于从演示文稿中提取文本)
  • pptxgenjs:
    npm install -g pptxgenjs
    (用于通过html2pptx创建演示文稿)
  • playwright:
    npm install -g playwright
    (用于html2pptx中的HTML渲染)
  • react-icons:
    npm install -g react-icons react react-dom
    (用于图标)
  • sharp:
    npm install -g sharp
    (用于SVG栅格化和图像处理)
  • LibreOffice:
    sudo apt-get install libreoffice
    (用于PDF转换)
  • Poppler:
    sudo apt-get install poppler-utils
    (用于通过pdftoppm将PDF转换为图片)
  • defusedxml:
    pip install defusedxml
    (用于安全XML解析)