md-to-pptx

md-to-pptx

Convert Markdown to PowerPoint or generate presentations with AI assistance.

Dependencies

Install required packages before use:

pip install python-pptx Pillow

Note: Use python3 instead of python on systems where Python 3 is not the default.

Workflow

Step 1: Gather Requirements

IMPORTANT: Before generating any content, you MUST ask the user the following questions using the AskUserQuestion tool:

PPT Slide Count: How many slides do you want the PPT to include?
- Options: 5-10 slides, 10-15 slides, 15-20 slides, more than 20 slides
Target Audience: Who is the target audience for this PPT?
- Options: Corporate executives/decision-makers, Technical team/developers, Students/educational settings, General public/customers
Presentation Context: In what context will this PPT be used?
- Options: Business report/meeting, Product launch/roadshow, Training/teaching, Academic report/research sharing
Template Selection: Do you want to use an existing PPT template?
- Options:
  - business (Business style - white background, dark blue titles)
  - tech_dark (Tech style - dark background, green accents)
  - education (Education style - warm background, orange accents)
  - neumorphism (Neumorphism style - modern blue and yellow style)
  - Do not use a template/custom

Additional questions to ask:

Source: Do you have an existing Markdown file, or should I generate content?
Save location: Where to save the PPT? (default: user's current working directory)

Use the answers to guide content generation:

Slide Count: Determines the depth and detail of content
Target Audience: Affects language complexity, terminology, and examples
Presentation Context: Influences tone, structure, and visual style
Template: Sets the visual theme for the presentation

Step 2: Determine Approach

If converting existing Markdown:

Read the Markdown file
Parse content into slides (H1/H2 headings create new slides)
Generate PPTX with appropriate layouts

If generating new content:

Create an outline based on user's topic
Present outline for user approval
Generate full Markdown content
Convert to PPTX

Step 3: Generate Presentation

Run the conversion script:

python scripts/md_to_pptx.py input.md -o output.pptx --theme business

Command Line Options

python scripts/md_to_pptx.py <input.md> [options]

Options:
  -o, --output      Output filename (default: input name + .pptx)
  -d, --directory   Output directory (default: user's current directory)
  -t, --theme       Theme: business, tech_dark, education, neumorphism
  --template        Path to custom .pptx template
  --no-template     Generate without using built-in template
  -q, --quiet       Suppress progress output
  --list-themes     Show available themes
  --list-templates  Show template locations

Examples

# Save to current directory (default)
python scripts/md_to_pptx.py presentation.md

# Specify output filename
python scripts/md_to_pptx.py presentation.md -o slides.pptx

# Save to Desktop
python scripts/md_to_pptx.py presentation.md -d ~/Desktop

# Use tech dark theme
python scripts/md_to_pptx.py presentation.md --theme tech_dark

# Use neumorphism theme
python scripts/md_to_pptx.py presentation.md --theme neumorphism

# Use custom template
python scripts/md_to_pptx.py presentation.md --template company.pptx

# Show available themes
python scripts/md_to_pptx.py --list-themes

# Show template locations
python scripts/md_to_pptx.py --list-templates

Built-in Templates

Four pre-built templates are included in assets/templates/:

Template	File	Description
business	`business_template.pptx`	White background, dark blue titles, professional
tech_dark	`tech_dark_template.pptx`	Dark gray background, green accents, developer-friendly
education	`education_template.pptx`	Warm cream background, orange accents, approachable
neumorphism	`蓝黄色新拟态行业调研报告PPT模板.pptx`	Blue-yellow neumorphism style, modern research report

Custom Templates

Place custom .pptx templates in assets/templates/ or specify path with --template:

# Use template from assets/templates/
python scripts/md_to_pptx.py input.md --template assets/templates/my_company.pptx

# Use template from any location
python scripts/md_to_pptx.py input.md --template /path/to/custom.pptx

To regenerate built-in templates:

python scripts/generate_templates.py -o assets/templates

Markdown Format

Key rules: # H1 creates title slide, ## H2 creates content slides, ### H3+ stays on current slide.

For detailed format reference including supported elements, image handling, and layout selection, see references/markdown-format.md.

Error Handling

The generator uses fault-tolerant mode:

Unsupported elements are skipped with warnings
Missing images show placeholder text
Malformed tables fall back to text
All warnings are collected and reported at the end

Progress Feedback

The script reports progress per slide:

📄 Reading: presentation.md
📊 Parsed 6 slides
📋 Using built-in template: tech_dark_template.pptx
[████████░░░░░░░░░░░░░░░░░░░░░░] 3/6 - Generating slide 3: Introduction...
✅ Created: /path/to/output.pptx

Python API

from scripts.md_to_pptx import convert_md_to_pptx, generate_from_content

# Convert file
success, output_path, warnings = convert_md_to_pptx(
    "presentation.md",
    output_path="slides.pptx",
    theme="business"
)

# Generate from content string
success, warnings = generate_from_content(
    "# My Title\n\n## Slide 1\nContent here",
    "output.pptx",
    theme="tech_dark"
)

Typical Interaction Flow

User: "Help me create a presentation about X"
Ask: Theme preference? Save location?
Generate outline, present for approval
User approves or requests changes
Generate full Markdown content
Run conversion script with chosen options
Report: Created X slides, saved to Y, any warnings