[!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 initcreates 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/--fontfor complete customisation - Comprehensive Command Structure:
deckbuilder template→ analyze, validate, document, enhance, listdeckbuilder config→ show, languages, completiondeckbuilder image→ generate, cropdeckbuilder 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