StandardSlide

Consistent slide deck generation for presentations with integrated text and images

StandardSlide provides a Python package for creating professional PowerPoint presentations from markdown content or direct API calls. It automatically applies standardized styling using the same color schemes as standardplot, supports markdown-based content definition, and generates polished PowerPoint presentations.

Features

• 🎯 Consistent Styling - Automatic application of professional templates with standardized colors and fonts
• 📝 Markdown Integration - Create slides from markdown files with simple syntax
• 🖼️ Smart Image Handling - Automatic image optimization, resizing, and layout
• 🎨 StandardPlot Integration - Uses identical color schemes for visual consistency across charts and slides
• ✅ Built-in Validation - Comprehensive validation system with detailed error reporting
• 📊 Professional Templates - Title slides and content slides with optimal layouts
• 🔧 Flexible API - Both programmatic and markdown-based workflows

Installation

Basic Installation

pip install -e .

With Development Dependencies

pip install -e .[dev]

With StandardPlot Integration

pip install -e .[standardplot]

Quick Start

Method 1: Direct API Usage

from standardslide import SlideDeck

# Create a new presentation
deck = SlideDeck()

# Add title slide
deck.add_title_slide(
    title="My Analysis Results",
    subtitle="Q4 Performance Review",
    author="Data Team",
    date="December 2024"
)

# Add content slides
deck.add_content_slide(
    title="Key Findings",
    images=["./figures/results_chart.png"],
    text_blocks=[
        "Our analysis reveals significant improvements:",
        "- Revenue increased by 25%",
        "- Customer satisfaction: 4.8/5.0",
        "- Operational efficiency up 15%"
    ]
)

# Save presentation
deck.save("my_presentation.pptx")

Method 2: Markdown-Based

Create a markdown file (slides.md):

# Executive Summary

![results](./figures/summary_chart.png)

Our Q4 analysis shows exceptional performance across all metrics.

Key achievements:
- Exceeded all quarterly targets
- Strong customer satisfaction ratings
- Improved operational efficiency

# Detailed Analysis

![performance](./figures/performance_metrics.png)
![comparison](./figures/before_after.png)

Performance highlights:
- Revenue growth: 25% YoY
- Cost reduction: 15%
- Market share expansion: 8%

## Strategic Recommendations

Based on our findings:
- Scale successful initiatives
- Invest in high-performing areas
- Monitor emerging opportunities

Generate presentation from markdown:

from standardslide import slides_from_markdown

deck = slides_from_markdown(
    markdown_path="slides.md",
    title="Q4 Analysis Results",
    author="Analytics Team"
)

deck.save("markdown_presentation.pptx")

Detailed Usage Guide

Creating Slide Decks

Basic Deck Creation

from standardslide import SlideDeck, create_slide_deck

# Method 1: Direct instantiation
deck = SlideDeck()

# Method 2: Using convenience function
deck = create_slide_deck()

# Method 3: With custom configuration
deck = SlideDeck(config_path="custom_config.json")

Adding Title Slides

deck.add_title_slide(
    title="Main Presentation Title",      # Required
    subtitle="Optional Subtitle",        # Optional
    author="Presenter Name",             # Optional
    date="December 2024"                 # Optional
)

Adding Content Slides

deck.add_content_slide(
    title="Slide Title",
    images=[                             # Optional list of image paths
        "./figures/chart1.png",
        "./figures/chart2.png"
    ],
    text_blocks=[                        # Optional list of text content
        "Main paragraph text here.",
        "- Bullet point 1",
        "- Bullet point 2",
        "",                              # Empty string creates spacing
        "Another paragraph after spacing."
    ]
)

Markdown Format Specification

StandardSlide uses a specific markdown format for slide generation:

Slide Boundaries

• Each # header creates a new slide
• The header text becomes the slide title

Images

• Use standard markdown image syntax: ![alt text](path/to/image.png)
• Images are automatically positioned on the left side of slides
• Supports relative and absolute paths
• Multiple images per slide are supported

Text Content

• Regular paragraphs become text blocks
• Bullet points are created with - or *
• Empty lines create spacing between content blocks
• Text is positioned on the right side when images are present

Example Markdown Structure

# First Slide Title

![chart](./figures/chart1.png)

This paragraph will appear as text on the slide.

Key points:
- Point 1
- Point 2
- Point 3

# Second Slide Title

Multiple paragraphs and images supported.

![image1](./figures/image1.png)
![image2](./figures/image2.png)

- Works with multiple images
- Automatic layout optimization

Working with Images

Supported Formats

• PNG, JPEG, GIF, BMP
• Automatic format conversion if needed
• Optimal sizing for presentation quality

Image Handling Features

from standardslide.utils import image_handler

# Check if image exists and is valid
is_valid = image_handler.validate_image_path("./figures/chart.png")

# Create placeholder images for testing
image_handler.create_image_placeholder(
    width=800, 
    height=600, 
    text="Chart Placeholder",
    output_path="./figures/placeholder.png"
)

Image Path Resolution

• Relative paths in markdown are resolved relative to the markdown file location
• Absolute paths are used as-is
• Missing images are automatically replaced with informative placeholders

Validation and Error Handling

StandardSlide includes comprehensive validation:

Slide Validation

# Validate individual slide data
slide_data = {
    'title': 'Test Slide',
    'images': ['./figures/chart.png'],
    'text_blocks': ['Some text content']
}

validation = deck.validator.validate_slide_data(slide_data)
print(f"Valid: {validation['valid']}")
print(f"Errors: {validation['errors']}")
print(f"Warnings: {validation['warnings']}")

Presentation Validation

# Validate entire presentation
validation = deck.validate_presentation()

if not validation['valid']:
    print("Presentation has errors:")
    for error in validation['errors']:
        print(f"  - {error}")

if validation['warnings']:
    print("Warnings:")
    for warning in validation['warnings']:
        print(f"  - {warning}")

File Management

Saving Presentations

# Basic save
output_path = deck.save("presentation.pptx")

# Save with subfolder organization
output_path = deck.save("monthly_report.pptx", subfolder="reports/2024")

# The file will be saved to: ./presentations/reports/2024/monthly_report.pptx

File Structure

your_project/
├── figures/                    # Image assets
│   ├── chart1.png
│   └── chart2.png
├── presentations/              # Generated presentations
│   ├── examples/
│   │   ├── basic_example.pptx
│   │   └── markdown_example.pptx
│   └── reports/
│       └── monthly_report.pptx
├── slides.md                   # Markdown source
└── your_script.py             # Your Python code

Advanced Features

Custom Configuration

Create a JSON configuration file to override defaults:

{
    "slide": {
        "width_inches": 10,
        "height_inches": 7.5,
        "background_color": "#fafafa"
    },
    "fonts": {
        "title_font": "Calibri",
        "title_size": 36,
        "body_font": "Calibri",
        "body_size": 16
    },
    "colors": {
        "primary": "#2c5aa0",
        "secondary": "#e17a47"
    }
}

Load custom configuration:

deck = SlideDeck(config_path="my_config.json")

Color Palette Information

# Get color palette details
palette_info = deck.get_color_palette_info()

print(f"Using: {palette_info['name']}")
print(f"Background: {palette_info['background']['hex']}")

# Access specific colors
for color_key, color_info in palette_info['colors'].items():
    print(f"{color_key}: {color_info['hex']} - {color_info['use']}")

Creating Markdown Templates

from standardslide import create_example_markdown

# Create example markdown file
content = create_example_markdown("my_template.md")

# Or generate from existing slide data
template_content = deck.create_markdown_template("output_template.md")

Integration with StandardPlot

StandardSlide works seamlessly with standardplot for chart generation:

# 1. Generate charts with standardplot
import matplotlib.pyplot as plt
import seaborn as sns

# Create chart using standardplot styling
plt.figure(figsize=(10, 6))
sns.barplot(data=data, x='category', y='value')
plt.title('Performance Metrics')
plt.savefig('./figures/performance_chart.png', dpi=300, bbox_inches='tight')

# 2. Reference in markdown
markdown_content = """
# Performance Analysis

![performance](./figures/performance_chart.png)

The analysis shows significant improvements across all categories.
"""

# 3. Generate slides
deck = slides_from_markdown_content(markdown_content)
deck.save("analysis_presentation.pptx")

Examples

Running the Examples

# Run comprehensive examples
python example.py

This creates:

• presentations/examples/basic_api_example.pptx - Direct API usage
• presentations/examples/markdown_example.pptx - Markdown-based slides
• demo_slides.md - Example markdown file
• slide_template.md - Template for new presentations
• figures/ - Demo images

Example Use Cases

Academic Presentations

deck = SlideDeck()
deck.add_title_slide("Research Findings", "PhD Defense", "Student Name", "2024")
deck.add_content_slide("Methodology", 
                      images=["./figures/methodology.png"],
                      text_blocks=["Research approach...", "- Method 1", "- Method 2"])
deck.save("defense_presentation.pptx")

Business Reports

deck = slides_from_markdown("quarterly_report.md", 
                           title="Q4 Business Review",
                           author="Analytics Team")
deck.save("q4_report.pptx", subfolder="quarterly_reports")

Data Analysis Presentations

# Generate charts first
create_analysis_charts()  # Your function to create charts

# Create presentation from markdown
deck = slides_from_markdown("analysis.md")
validation = deck.validate_presentation()
if validation['valid']:
    deck.save("data_analysis.pptx")

Troubleshooting

Common Issues

Missing Images

• Problem: Images don't appear in slides
• Solution: Check image paths are correct and files exist
• Note: Missing images are replaced with informative placeholders

Import Errors

• Problem: ImportError: python-pptx is required
• Solution: Install dependencies with pip install -e .

Validation Warnings

• Problem: Presentation validation shows warnings
• Solution: Check image paths and slide content structure
• Note: Warnings don't prevent presentation creation

Validation Commands

# Test package installation
python -c "from standardslide import SlideDeck; print('Import successful')"

# Validate package version
python -c "import standardslide; print(f'StandardSlide v{standardslide.__version__} ready')"

# Run examples to test functionality
python example.py

Development

Project Structure

standardslide/
├── __init__.py          # Main API and SlideDeck class
├── config.py            # Configuration management
├── templates.py         # PowerPoint slide templates
├── parser.py            # Markdown parsing and generation
└── utils.py             # Image handling, validation, file management

Testing Your Installation

# Quick functionality test
from standardslide import SlideDeck

deck = SlideDeck()
deck.add_title_slide("Test", "Installation Check")
deck.add_content_slide("Success", text_blocks=["StandardSlide is working!"])
path = deck.save("test_presentation.pptx")
print(f"Test presentation saved: {path}")

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with python example.py
5. Submit a pull request

Support

For issues and questions:

• Check the examples in example.py
• Review validation output for specific error messages
• Ensure all image paths are accessible
• Verify python-pptx and Pillow are installed correctly