# PPTX-RS Specification
## Overview
`ppt-rs` is a Rust library for generating, reading, and modifying Microsoft PowerPoint 2007+ (.pptx) files following the ECMA-376 Office Open XML standard.
## Design Philosophy
### 1. Progressive Disclosure
The library provides multiple API layers:
- **Prelude** (`ppt_rs::prelude::*`) — Simple, discoverable API for common tasks
- **Helpers** (`helpers::colors`, `helpers::tables`) — Convenient utilities for frequent operations
- **Core** (`Shape`, `Table`, `Chart`) — Full control when needed
### 2. Type Safety Over Convenience
- All operations use `Result<T, PptxError>` for explicit error handling
- Compile-time validation where possible (dimension units, color formats)
- No panics in public API — all errors are recoverable
### 3. Zero-Cost Abstractions
- Helper functions and extension methods add no runtime overhead
- Fluent APIs compile to the same code as direct construction
- Lazy loading for large presentations without memory bloat
### 4. OOXML Compliance
- Generated files follow ECMA-376 standard exactly
- Tested against Microsoft PowerPoint, LibreOffice, Google Slides
- Preserves unknown elements when reading existing files (round-trip safe)
## Testing Strategy
The library employs a layered testing approach:
| Unit tests | 850+ | Individual module correctness |
| Integration tests | 70+ | End-to-end workflows |
| Compatibility tests | 6 | PowerPoint/LibreOffice/Google Slides validation |
| Doc tests | 50+ | API examples in documentation |
### Quality Gates
- All tests must pass (100% required)
- Zero compiler warnings
- Clippy clean
- Generated PPTX files validate against `PptxValidator`
## API Stability
### Semantic Versioning
- **MAJOR**: Breaking changes to core API (rare)
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, documentation improvements
### Current Stability
- Core API (`Presentation`, `SlideContent`, `Shape`): Stable
- Prelude API: Stable
- Helper modules: Evolving (may add new convenience functions)
- Internal traits (`ToXml`, `Positioned`): Subject to change
### Deprecation Policy
- Deprecated items marked with `#[deprecated(since = "x.y.z", note = "...")]`
- Minimum 2 minor versions before removal
- Migration guides in release notes
## File Format Specification
### PPTX Structure
A PPTX file is a ZIP archive containing XML and binary files:
```
presentation.pptx
├── [Content_Types].xml # MIME type declarations
├── _rels/
│ └── .rels # Package relationships
├── ppt/
│ ├── presentation.xml # Main presentation
│ ├── _rels/
│ │ └── presentation.xml.rels
│ ├── slides/ # Individual slides
│ ├── slideLayouts/ # Layout templates
│ ├── slideMasters/ # Master slides
│ ├── theme/ # Theme definitions
│ ├── media/ # Images, videos, audio
│ ├── charts/ # Embedded charts
│ └── notesSlides/ # Speaker notes
└── docProps/
├── core.xml # Document properties
└── app.xml # Application properties
```
### XML Namespaces
| `a` | `http://schemas.openxmlformats.org/drawingml/2006/main` | Drawing ML |
| `p` | `http://schemas.openxmlformats.org/presentationml/2006/main` | Presentation ML |
| `r` | `http://schemas.openxmlformats.org/officeDocument/2006/relationships` | Relationships |
| `c` | `http://schemas.openxmlformats.org/drawingml/2006/chart` | Charts |
### Units
The library uses EMU (English Metric Units) internally:
| 1 inch | 914,400 EMU |
| 1 cm | 360,000 EMU |
| 1 point | 12,700 EMU |
| 1 mm | 36,000 EMU |
## API Specification
### Prelude Module
The prelude provides a simplified API:
```rust
use ppt_rs::prelude::*;
// Macros
pptx!("Title") // Create QuickPptx builder
shape!(rect x, y, w, h) // Create rectangle shape
shape!(circle x, y, size) // Create circle shape
// Unit Conversions
inches(1.0) -> 914400 // Convert inches to EMU
cm(2.54) -> 914400 // Convert cm to EMU
pt(72.0) -> 914400 // Convert points to EMU
// Shape Builders
shapes::rect(x, y, w, h) // Rectangle (inches)
shapes::circle(x, y, d) // Circle (inches)
shapes::rounded_rect(x, y, w, h) // Rounded rectangle
shapes::text_box(x, y, w, h, text)// Text box
shapes::colored(shape, fill, line)// Apply colors
shapes::gradient(shape, start, end, dir)// Apply gradient
// Color Constants
colors::RED, colors::BLUE, colors::GREEN
colors::CORPORATE_BLUE, colors::CORPORATE_GREEN
```
### Core Types
#### SlideContent
```rust
SlideContent::new("Title")
.add_bullet("Text") // Add bullet point
.add_notes("Speaker notes") // Add speaker notes
.layout(SlideLayout::TwoColumn) // Set layout
.table(table) // Add table
.with_shapes(shapes) // Add shapes
.with_image(image) // Add image
.with_chart(chart) // Add chart
```
#### SlideLayout
| `TitleOnly` | Title at top only |
| `CenteredTitle` | Centered title |
| `TitleAndContent` | Title with bullets (default) |
| `TitleAndBigContent` | Title with large content |
| `TwoColumn` | Two-column layout |
| `Blank` | Empty slide |
#### Shape
```rust
Shape::new(ShapeType::Rectangle, x, y, width, height)
.with_fill(ShapeFill::new("FF0000"))
.with_line(ShapeLine::new("000000", 12700))
.with_text("Text")
.with_gradient(GradientFill::linear("start", "end", direction))
.with_transparency(50)
.with_id(id) // Fixed ID for connectors
```
#### ShapeType (100+ types)
| Basic | Rectangle, Circle, Ellipse, Triangle, Diamond |
| Arrows | ArrowRight, ArrowLeft, ArrowUp, ArrowDown, etc. |
| Stars | Star4, Star5, Star6, Star8, Star12, Star16, Star24, Star32 |
| Callouts | RoundedRectCallout, WedgeCallout, CloudCallout |
| Flowchart | Process, Decision, Data, Document, Terminator |
| Other | Heart, Lightning, Moon, Sun, Cloud |
#### Connector
```rust
Connector::straight(x1, y1, x2, y2)
Connector::elbow(x1, y1, x2, y2)
Connector::curved(x1, y1, x2, y2)
.with_line(ConnectorLine::new("color", width))
.with_end_arrow(ArrowType::Triangle)
.with_start_arrow(ArrowType::Oval)
.with_arrow_size(ArrowSize::Large)
.anchored_to(start_shape_id, end_shape_id)
```
#### Table
```rust
TableBuilder::new(vec![col_widths])
.add_simple_row(vec!["Cell 1", "Cell 2"])
.add_row(TableRow::new(vec![
TableCell::new("Text")
.bold()
.italic()
.text_color("FFFFFF")
.background_color("4472C4")
.align(CellAlign::Center)
.valign(CellVAlign::Middle)
]))
.position(x, y)
.build()
```
#### Chart
```rust
ChartBuilder::new("Title", ChartType::Bar)
.categories(vec!["Q1", "Q2", "Q3"])
.add_series(ChartSeries::new("2023", vec![100.0, 150.0, 120.0]))
.build()
```
| `Bar` | Vertical bar chart |
| `BarClustered` | Clustered bar chart |
| `BarStacked` | Stacked bar chart |
| `Line` | Line chart |
| `LineSmooth` | Smooth line chart |
| `Pie` | Pie chart |
| `Pie3D` | 3D pie chart |
| `Doughnut` | Doughnut chart |
| `Area` | Area chart |
| `AreaStacked` | Stacked area chart |
| `Scatter` | Scatter plot |
| `Radar` | Radar chart |
| `Bubble` | Bubble chart |
#### GradientFill
```rust
GradientFill::linear("start_color", "end_color", GradientDirection::Horizontal)
GradientFill::three_color("start", "middle", "end", direction)
GradientFill::custom(vec![
GradientStop::new("color1", 0, 0), // position 0%, transparency 0%
GradientStop::new("color2", 50, 25), // position 50%, transparency 25%
GradientStop::new("color3", 100, 0), // position 100%, transparency 0%
], angle)
```
| Horizontal | 0° |
| Vertical | 90° |
| DiagonalDown | 45° |
| DiagonalUp | 135° |
| Angle(n) | n° |
#### Image Effects (v0.2.10)
**Simplified API** - Chainable methods with auto-detection:
```rust
use ppt_rs::generator::ImageBuilder;
use ppt_rs::prelude::inches;
// Simple: Load from file (auto-detects format)
let img = ImageBuilder::from_file("photo.jpg")
.at(inches(1.0), inches(2.0))
.build();
// Auto-detect format from bytes
let img = ImageBuilder::auto(bytes)
.at(inches(2.0), inches(3.0))
.build();
// Chainable effects
let img = ImageBuilder::from_file("photo.jpg")
.at(inches(1.0), inches(2.0))
.shadow() // Add shadow
.reflection() // Add reflection
.glow() // Add glow
.build();
// With sizing and cropping
let img = ImageBuilder::from_file("photo.jpg")
.size(inches(3.0), inches(2.0))
.at(inches(2.0), inches(3.0))
.crop(0.1, 0.1, 0.1, 0.1) // 10% crop from all sides
.build();
```
**Legacy API** - Still supported:
```rust
// Explicit width/height/format
ImageBuilder::from_bytes(bytes, 2000000, 2000000, "JPEG")
.position(500000, 1500000)
.build_with_shadow()
// Base64 with explicit parameters
ImageBuilder::from_base64(data, 2000000, 2000000, "PNG")
.position(800000, 1200000)
.build_with_reflection()
```
| Shadow | Outer drop shadow with blur and offset | `<a:outerShdw>` |
| Reflection | Mirror effect below image | `<a:reflection>` |
| Glow | Golden aura around image | `<a:glow>` |
| Soft Edges | Feathered/vignette borders | `<a:softEdge>` |
| Inner Shadow | Inset shadow for depth | `<a:innerShdw>` |
| Blur | Artistic defocus effect | `<a:blur>` |
| Crop | Percentage-based edge trimming | `<a:srcRect>` |
**Supported Image Formats:**
- JPEG/JPG - Full support with all effects
- PNG - Full support with all effects
- GIF - Basic support
### HTML to PPTX
The CLI and library convert HTML to PowerPoint:
```bash
pptcli html2ppt input.html [output.pptx] [--title "Title"] [options]
```
#### Supported HTML Elements
| `<h1>` | New slide with title |
| `<h2>`–`<h6>` | Bold section headers |
| `<p>` | Bullet points / paragraphs |
| `<ul>`/`<ol>` with `<li>` | List items |
| `<table>` with `<tr>`/`<th>`/`<td>` | Table with styled header row |
| `<pre>`/`<code>` | Code blocks |
| `<img>` | Image placeholders (with alt text) |
| `<blockquote>` | Speaker notes |
| `<strong>`/`<b>` | Bold text |
| `<em>`/`<i>` | Italic text |
| `<a href="...">` | Hyperlink text |
| `<hr>` | Slide break |
| `<br>` | Line break |
| `<title>` | Presentation title (falls back to first `<h1>`) |
#### Inline CSS Support
- `color` — Text color (named, hex `#RRGGBB`, `rgb()`, `rgba()`)
- `font-size` — Font size in px/pt
- `font-weight` — Bold (700+)
- `font-style` — Italic
- `text-align` — left, center, right
- `background-color` — Text highlight / background
#### API
```rust
use ppt_rs::import::{parse_html, parse_html_with_options, Html2Ppt, HtmlParseOptions};
// Quick parse
let slides = parse_html(html)?;
// With options
let options = HtmlParseOptions::new()
.max_slides(20)
.max_bullets(8)
.include_code(true)
.include_tables(true)
.include_images(false);
let slides = Html2Ppt::with_options(options).parse(html)?;
// Parse from file
let slides = Html2Ppt::new().parse_file("page.html")?;
```
#### CLI Options
| `--title` | HTML `<title>` | Presentation title override |
| `--max-slides` | 50 | Maximum slides to generate |
| `--max-bullets` | 10 | Maximum bullet points per slide |
| `--no-images` | false | Disable image placeholders |
| `--no-tables` | false | Disable table extraction |
| `--no-code` | false | Disable code block extraction |
### Markdown to PPTX
The CLI converts Markdown to PPTX:
```bash
pptcli md2ppt input.md [output.pptx] [--title "Title"]
```
#### Supported Markdown Syntax
| `# Heading` | New slide with title |
| `## Subheading` | Bold bullet point |
| `- Bullet` | Bullet point |
| `1. Item` | Numbered list |
| `**bold**` | Bold text |
| `*italic*` | Italic text |
| `` `code` `` | Inline code |
| `> Quote` | Speaker notes |
| `\| Table \|` | GFM table |
| ` ```code``` ` | Syntax-highlighted code |
| ` ```mermaid ` | Mermaid diagram |
| `---` | Slide break |
#### Syntax Highlighting
Code blocks use Solarized Dark theme:
| Keywords | Blue (#268BD2) |
| Functions | Yellow (#B58900) |
| Strings | Cyan (#2AA198) |
| Operators | Green (#859900) |
| Numbers | Violet (#6C71C4) |
| Comments | Gray (#586E75) |
#### Mermaid Diagrams (12 types)
| `flowchart` | Flowchart with nodes and edges |
| `sequenceDiagram` | Sequence diagram with participants |
| `pie` | Pie chart |
| `gantt` | Gantt chart with tasks |
| `classDiagram` | UML class diagram |
| `stateDiagram` | State machine diagram |
| `erDiagram` | Entity-relationship diagram |
| `mindmap` | Mind map |
| `timeline` | Timeline |
| `journey` | User journey map |
| `quadrantChart` | Quadrant chart |
| `gitGraph` | Git commit graph |
### Repair Capability
```rust
use ppt_rs::PptxRepair;
let mut repair = PptxRepair::open("file.pptx")?;
let issues = repair.validate();
let result = repair.repair();
if result.is_valid {
repair.save("repaired.pptx")?;
}
```
#### Detectable Issues
- Missing required parts
- Invalid XML structure
- Broken relationships
- Orphan slides
- Invalid content types
### Reading & Editing
```rust
use ppt_rs::oxml::{PresentationReader, PresentationEditor};
// Read presentation info
let reader = PresentationReader::open("file.pptx")?;
let info = reader.presentation_info()?;
println!("Slides: {}", info.slide_count);
// Edit presentation
let mut editor = PresentationEditor::open("file.pptx")?;
editor.add_slide(SlideContent::new("New Slide"))?;
editor.update_slide(0, SlideContent::new("Updated"))?;
editor.remove_slide(1)?;
editor.save("modified.pptx")?;
```
### Export to HTML
```rust
use ppt_rs::api::Presentation;
let pres = Presentation::with_title("My Presentation")
.add_slide(SlideContent::new("Slide 1").add_bullet("Point"));
pres.save_as_html("output.html")?;
```
### Export to Markdown (v0.2.12)
```rust
use ppt_rs::api::Presentation;
use ppt_rs::export::md::MarkdownOptions;
let pres = Presentation::with_title("My Presentation")
.add_slide(SlideContent::new("Slide 1").add_bullet("Point"));
// Simple export
pres.save_as_markdown("output.md")?;
// With options
let options = MarkdownOptions::new()
.with_slide_numbers(true)
.with_frontmatter(true)
.with_gfm_tables(true)
.with_notes(true);
pres.save_as_markdown_with_options("output.md", &options)?;
```
**Markdown Export Features:**
- YAML frontmatter with presentation metadata
- GFM tables for slide tables
- Code blocks with syntax highlighting
- Speaker notes as blockquotes
- Configurable slide separators
- Image references
### Export to Images (v0.2.12)
```rust
use ppt_rs::api::Presentation;
use ppt_rs::export::image_export::{ImageExportOptions, ImageFormat};
let pres = Presentation::with_title("My Presentation")
.add_slide(SlideContent::new("Slide 1"))
.add_slide(SlideContent::new("Slide 2"));
// Export all slides
let options = ImageExportOptions::new()
.with_format(ImageFormat::Png)
.with_dpi(150);
let paths = pres.save_as_images("output_dir/", &options)?;
// Export single slide
let options = ImageExportOptions::new()
.with_format(ImageFormat::Png)
.with_slide(1);
pres.save_slide_as_image(1, "slide1.png", &options)?;
// Generate thumbnail
pres.save_thumbnail("thumbnail.png", 300)?;
```
**Image Export Options:**
| `format` | PNG | PNG or JPEG |
| `dpi` | 150 | Resolution (96-300+) |
| `jpeg_quality` | 90 | JPEG quality (0-100) |
| `width/height` | 0 | Dimensions in pixels (0 = auto) |
| `slide_number` | 0 | 0 = all, 1+ = specific |
**Presets:**
- `ImageExportOptions::high_quality()` — 300 DPI PNG
- `ImageExportOptions::web_optimized()` — 96 DPI JPEG
### Compression (v0.2.12)
```rust
use ppt_rs::api::Presentation;
use ppt_rs::opc::compress::CompressionOptions;
let pres = Presentation::with_title("Large Presentation")
.add_slide(SlideContent::new("Slide 1"));
// Analyze file size
let analysis = pres.analyze_size()?;
println!("{}", analysis.summary());
// Compress with default options
let options = CompressionOptions::new();
let result = pres.compress("compressed.pptx", &options)?;
println!("Reduced by {:.1}%", result.reduction_percent);
// Use web optimization preset
let options = CompressionOptions::web();
let result = pres.compress("web_optimized.pptx", &options)?;
```
**Compression Features:**
| Remove unused media | Deletes unreferenced images/audio |
| Remove properties | Strips document metadata |
| Remove notes | Deletes speaker notes slides |
| Remove comments | Deletes presentation comments |
| XML optimization | Minimizes whitespace |
| Target size | Optimize until size reached |
**Compression Levels:**
| Light | 95% | 2048px | Minimal change |
| Medium | 85% | 1600px | Balanced |
| Aggressive | 70% | 1280px | Maximum reduction |
| Custom(n) | n% | 1600px | User defined |
**Presets:**
- `CompressionOptions::maximum()` — All aggressive optimizations
- `CompressionOptions::web()` — 5MB target, web-ready
## CLI Commands
```bash
pptcli create <title> [output] [--slides N] # Create presentation
pptcli md2ppt <input.md> [output.pptx] [--title] # Convert markdown
pptcli html2ppt <input.html> [output.pptx] [--title] # Convert HTML (also `from-html`, `from-html-file`)
pptcli pdf2ppt <input.pdf> [output.pptx] # Convert PDF
pptcli validate <file.pptx> # Validate PPTX
pptcli info <file.pptx> # Show info
pptcli repair <input.pptx> <output.pptx> # Repair PPTX
```
## Compatibility
| Microsoft PowerPoint 2007+ | ✅ Full support |
| LibreOffice Impress | ✅ Full support |
| Google Slides | ✅ Full support |
| Apple Keynote | ✅ Import support |
| WPS Office | ✅ Full support |
## Performance
| File size overhead | ~10-15 KB base |
| Generation speed | ~1000 slides/sec |
| Memory usage | ~2 MB + content |
| Test coverage | 850+ tests |
## Error Handling
```rust
use ppt_rs::{PptxError, Result};
// All operations return Result<T, PptxError>
match create_pptx("title", 5) {
Ok(data) => { /* success */ }
Err(PptxError::Io(e)) => { /* I/O error */ }
Err(PptxError::Zip(e)) => { /* ZIP error */ }
Err(PptxError::XmlParse(e)) => { /* XML error */ }
Err(PptxError::InvalidOperation(msg)) => { /* logic error */ }
}
```
## Version History
| 0.2.13 | MCP server (8 tools), codebase cleanup, documentation refresh | **MCP integration milestone** — AI assistant integration via Model Context Protocol |
| 0.2.12 | Markdown export, image export (PNG/JPEG), PPTX compression | **Export & optimization milestone** — full round-trip capabilities |
| 0.2.11 | Color aliases (40+), table helpers, extension methods, API guide | **API simplification milestone** — introduced helper pattern for 60% less boilerplate |
| 0.2.10 | Image effects system (8 effects), ImageBuilder chainable API, JPEG fix |
| 0.2.9 | Compatibility test sorting fix |
| 0.2.8 | Compatibility testing infrastructure (PptxValidator, CompatibilityTestSuite) |
| 0.2.7 | Streaming ZIP and lazy loading |
| 0.2.6 | Error handling refactoring, From<ZipError> |
| 0.2.5 | Codebase cleanup, merged table modules |
| 0.2.4 | Dimension API (EMU, inches, cm, pt, ratio), trait refactoring |
| 0.2.3 | Transitions, connectors, gradients, cell merging, charts |
| 0.2.1 | Bullet styles, text enhancements, image from URL/base64 |
| 0.2.0 | Templates, prelude, themes, layout helpers |
| 0.1.8 | Prelude, gradients, transparency, connectors |
| 0.1.7 | 12 Mermaid diagram types |
| 0.1.6 | Syntax highlighting |
| 0.1.5 | Enhanced markdown parsing |
| 0.1.4 | Table text rendering fix |
| 0.1.3 | Modular table module |
| 0.1.2 | Animations, transitions, SmartArt |
| 0.1.1 | Extended parts support |
| 0.1.0 | Initial release |