[!IMPORTANT]
Deckbuilder is currently under active development and should NOT be considered production ready.

🎯 Deckbuilder

Create professional PowerPoint presentations from Markdown or JSON

Deckbuilder is a Python library, Command Line tool, and MCP server that generates PowerPoint presentations from structured content. Focus on your content - Deckbuilder handles the formatting and layout.

✨ Key Features

🚀 One-Shot Presentation Generation

Create complete PowerPoint presentations from JSON or Markdown with YAML frontmatter in a single command.

🎨 Rich Content Support

Advanced Formatting: **bold**, *italic*, ___underline___, ***bold italic***
Language & Font updating: The ability to update the fonts and language of all slide objects using the command line tools using the CLI.
Professional Tables: Custom styling with themes, colors, and precise dimension controls (column widths, row heights, table sizing).
Supported Layouts: Progressive library of templates being added.

🧠 Smart Template System

Intelligent Layout Selection: Automatic layout recommendations based on content type
Pattern-Based Architecture: Customize any layout with your own templates
Rich Content Support: Tables, images, multi-column layouts with professional styling

🖼️ Smart Image Processing

Automatic Image Fallbacks: Missing images? Deckbuilder generates professional placeholders automatically
Smart Cropping: Face detection and intelligent composition for perfect image sizing
Professional Filters: Business-appropriate styling with grayscale and other effects

⚡ Enhanced CLI Experience

Professional Hierarchical Interface: Clean command structure (deckbuilder <command> <subcommand>)
One-Command Setup: deckbuilder init creates templates and configuration
Context-Aware Paths: CLI args > env vars > current directory precedence
Always Local Output: CLI outputs to current directory for predictable local development
Global Arguments: -t/--template-folder, -l/--language, -f/--font for complete customisation
Comprehensive Command Structure:
- deckbuilder template → analyze, validate, document, enhance, list
- deckbuilder config → show, languages, completion
- deckbuilder image → generate, crop
- deckbuilder remap → update existing PowerPoint files with language/font changes
Template Management: Analyze, validate, and enhance PowerPoint templates with detailed validation

🚀 Quick Start

Installation

pip install deckbuilder

CLI Usage (Standalone)

# Initialize templates (one-time setup) This will create the default template and mapping JSON.
deckbuilder init

# Create presentation from markdown (outputs to current directory)
deckbuilder create presentation.md

# Use custom template folder (CLI arg overrides env vars)
deckbuilder --template-folder /custom/templates create presentation.md

# Create with custom language and font (supports both formats)
deckbuilder create presentation.md --language "es-ES" --font "Arial"
deckbuilder create presentation.md --language "Spanish (Spain)" --font "Times New Roman"

# View supported languages
deckbuilder config languages

# Template management & intelligence
deckbuilder template analyze default --verbose
deckbuilder template validate default
deckbuilder template list

# Smart template recommendations available through MCP tools

# Image generation with crop-first approach
deckbuilder image generate 800 600 --filter grayscale
deckbuilder image crop image.jpg 800 600

# Language and font remapping for existing PowerPoint files
deckbuilder remap existing.pptx --language en-US --font Arial

# View current configuration (shows path sources)
deckbuilder config show

# Get help
deckbuilder --help

MCP Server (Claude Desktop)

Add to your Claude Desktop configuration:

Option 1: Direct installation (recommended)

{
  "mcpServers": {
    "deckbuilder": {
      "command": "deckbuilder-server",
      "env": {
        "DECK_TEMPLATE_FOLDER": "/Users/username/Documents/Deckbuilder/Templates",
        "DECK_TEMPLATE_NAME": "default",
        "DECK_OUTPUT_FOLDER": "/Users/username/Documents/Deckbuilder",
        "DECK_PROOFING_LANGUAGE": "en-AU",
        "DECK_DEFAULT_FONT": "Calibri"
      }
    }
  }
}

New Environment Variables:

DECK_PROOFING_LANGUAGE: Set proofing language for spell-check and grammar (accepts both "en-AU" and "English (Australia)" formats)
DECK_DEFAULT_FONT: Set default font family for all presentations
Default Language: Australian English (en-AU) if not specified

📝 Usage Examples

Markdown with Frontmatter (Recommended)

---
layout: Title Slide
---
# **Deckbuilder** Presentation
## Creating presentations with *content-first* intelligence

---
layout: Four Columns
title: Feature Comparison
columns:
  - title: Performance
    content: "**Fast** processing with optimized algorithms"
  - title: Security
    content: "***Enterprise-grade*** encryption and compliance"
  - title: Usability
    content: "*Intuitive* interface with minimal learning curve"
  - title: Cost
    content: "___Transparent___ pricing with proven ROI"
---

---
layout: Picture with Caption
title: Market Analysis
media:
  image_path: "charts/revenue_growth.png"  # Auto-fallback to PlaceKitten if missing
  alt_text: "Revenue growth chart"
  caption: "**Q4 Revenue Growth** - 23% increase"
---

---
layout: Title and Content
title: "**Table Dimensions:** Custom Column Widths"
style: dark_blue_white_text
row_style: alternating_light_gray
border_style: thin_gray
column_widths: [8, 6, 4, 5]
row_height: 0.9
content: |
  Sales Performance Report with individual column width control:

  | **Product Category** | **Q1 Sales** | **Q2** | **Growth %** |
  | Enterprise Software | $125,000 | $142,000 | +13.6% |
  | SaaS Solutions | $89,500 | $98,200 | +9.7% |
  | Cloud Services | $156,000 | $178,000 | +14.1% |
  | Mobile Apps | $67,300 | $73,800 | +9.7% |
---

---
layout: Title and Content
title: "**Table Dimensions:** Equal Column Distribution"
style: light_blue_dark_text
row_style: alternating_light_gray
border_style: thin_gray
table_width: 22
row_height: 0.9
content: |
  Team Performance Dashboard with equal column distribution:

  | **Team Member** | **Projects** | **Completed** | **Success Rate** |
  | Alice Johnson | 25 | 24 | 96% |
  | Bob Smith | 18 | 17 | 94% |
  | Carol Davis | 32 | 31 | 97% |
  | David Wilson | 21 | 20 | 95% |

JSON Format (Programmatic)

{
  "presentation": {
    "slides": [
      {
        "type": "Title Slide",
        "title": "**Deckbuilder** Presentation",
        "subtitle": "Content-first presentation generation"
      },
      {
        "type": "Title and Content",
        "title": "Key Benefits",
        "content": [
          "**Intelligent** content analysis",
          "*Semantic* layout recommendations",
          "***Professional*** template system"
        ]
      },
      {
        "type": "Title and Content",
        "title": "Team Performance Dashboard",
        "table": {
          "column_widths": [6, 4, 5, 3],
          "row_height": 1.8,
          "data": [
            ["**Team Member**", "**Projects**", "**Completed**", "**Rate**"],
            ["Alice Johnson", "25", "24", "96%"],
            ["Bob Smith", "18", "17", "94%"],
            ["Carol Davis", "32", "31", "97%"]
          ],
          "header_style": "dark_blue_white_text",
          "row_style": "alternating_light_gray",
          "border_style": "thin_gray"
        }
      }
    ]
  }
}

Python API

from deckbuilder import Deckbuilder

# Initialize engine
db = Deckbuilder()

# Create from markdown
result = db.create_presentation_from_markdown(
    markdown_content=open("presentation.md").read(),
    fileName="My_Presentation"
)

# Create from JSON
result = db.create_presentation(
    json_data={"presentation": {"slides": [...]}},
    fileName="JSON_Presentation"
)

print(f"✅ Created: {result}")

🌍 Language & Font Support

Supported Languages (20)

Deckbuilder supports 20 proofing languages for spell-check and grammar. You can use either locale codes (en-AU) or full names (English (Australia)):

# View all supported languages (shows both formats)
deckbuilder config languages

Available Languages:

English (United States, United Kingdom, Canada, Australia)
Spanish (Spain, Mexico, Latin America)
French (France, Canada)
German (Germany, Austria, Switzerland)
Italian, Portuguese (Brazil, Portugal)
Chinese (Simplified, Traditional), Japanese, Korean
Dutch, Russian, Arabic

Font Customization

# Set language and font globally (supports both formats)
export DECK_PROOFING_LANGUAGE="en-AU"           # Locale code format
export DECK_PROOFING_LANGUAGE="English (Australia)"  # Full name format
export DECK_DEFAULT_FONT="Arial"

# Or use CLI arguments (both formats work)
deckbuilder create presentation.md --language "fr-CA" --font "Times New Roman"
deckbuilder create presentation.md --language "French (Canada)" --font "Arial"

# Check current settings (shows locale codes and descriptions)
deckbuilder config show

🖼️ PlaceKitten Image Processing

Smart Image Fallback System - When images are missing or invalid, PlaceKitten automatically generates professional placeholders:

from placekitten import PlaceKitten

pk = PlaceKitten()
placeholder = (pk.generate(1920, 1080, image_id=1)
                .smart_crop(1920, 1080)
                .apply_filter("grayscale")
                .save("professional_placeholder.jpg"))

Features:

✅ File Validation: Checks image existence, format, and accessibility
✅ Professional Styling: Automatic grayscale filtering for business context
✅ Smart Cropping: Computer vision-based cropping with face detection
✅ Performance Optimized: Intelligent caching prevents duplicate processing
✅ Seamless Integration: Zero user intervention required

🚀 What's New in v1.2.0

Smart Template Recommendations

Content Analysis: Automatically analyzes your content to suggest the best layouts
MCP Integration: Available through Claude Desktop with intelligent recommendations

Enhanced Image Processing

Better Image Sizing: Smart cropping ensures images fit perfectly without distortion
Automatic Fallbacks: Professional placeholder images when your images are missing

Improved Pattern System

User Customization: Create custom layout patterns in {template_folder}/patterns/
Dynamic Loading: All layouts now use flexible pattern files instead of hard-coded templates

🏗️ Architecture

    Your Content (Markdown/JSON)
              ↓
    ┌─────────────────────┐
    │   Content Analysis  │  ← Analyzes your content type and audience
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │ Template Selection  │  ← Recommends best layouts for your content
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │  PowerPoint Engine  │  ← Generates professional presentations
    └─────────┬───────────┘
              ↓
    Your Professional Presentation

🎨 Supported Markdown Layouts

✅ Currently Implemented

Title Slide - Opening slide with title and subtitle
Title and Content - Rich text with headings, paragraphs, bullets
Four Columns - Quad content areas with structured frontmatter
Two Content - Side-by-side content areas
Comparison - Left vs right comparison layout
Table - Data tables with professional styling
Section Header - Divider slides between topics
Picture with Caption - Image-focused slides with smart fallbacks

🚧 Progressive Implementation (50+ Planned)

Big Number displays, SWOT Analysis, Feature Matrix
Timeline, Process Flow, Organizational Chart
Dashboard, Metrics, Financial layouts
And 40+ more business presentation layouts

See Feature Documentation for detailed specifications.

🛠️ Development

Prerequisites

Python 3.11+
Virtual environments are recommended.

Development Install

git clone https://github.com/teknologika/deckbuilder.git
cd deckbuilder
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]

Code Quality Standards

# Format code (required before commits)
black --line-length 100 src/

# Check linting (required)
flake8 src/ tests/ --max-line-length=100 --ignore=E203,W503,E501

# Run tests (required)
pytest tests/

Contributing

Fork the repository
Create feature branch: git checkout -b feature-name
Follow code quality standards
Add comprehensive tests
Submit pull request with clear description

📚 Documentation

Complete Documentation - Full documentation index
Supported Templates - Complete layout library (26+ patterns)
Deckbuilder Library - Python API reference and classes
Command-Line Interface - CLI commands and usage examples
MCP Server - Smart template recommendations and MCP tools
PlaceKitten Library - Image processing with crop-first approach
PlaceKitten Source - Technical implementation details

🔧 Technology Stack

Python 3.11+ with modern type hints and comprehensive error handling
FastMCP for Model Context Protocol server implementation
python-pptx for PowerPoint generation and template manipulation
PyYAML for structured frontmatter processing
OpenCV + Pillow for computer vision and image processing
pytest for unit testing
Anthropic Claude - for most of the development gruntwork :-)

📋 Troubleshooting

Template not found:

# Create templates folder
deckbuilder init

# Check configuration
deckbuilder config

Permission denied when saving:

Verify output folder has write permissions
Ensure files aren't open in PowerPoint

MCP connection failures:

Verify virtual environment is activated
Check Python path in Claude Desktop config
Ensure all dependencies are installed

📄 License

Apache License 2.0 - See LICENSE file for details.

Built with ❤️ for intelligent presentation generation - Copyright Bruce McLeod

🚀 Get Started • 📖 Documentation • 🐛 Report Issues

Deckbuilder