Back to PPT Agent

PPT Agent Guide

Learn how to create beautiful presentations using PPT Agent's web interface and API

Quick Start

PPT Agent is a markdown-based presentation builder. You can create presentations through our user-friendly web interface or programmatically via our REST API.

Choose the method that best fits your workflow below.

Method 1: Web App Interface

1Access PPT Agent

Open your web browser and navigate to your PPT Agent instance. If you're running it locally, this is typically http://localhost:3000.

Expected result:
You'll see the PPT Agent interface with "PPT Agent" in the top-left corner and presentation controls.

2Open Presentation Selector

In the header, locate the presentation selector dropdown. It displays the current presentation name (starts with "Example Presentation" by default).

Visual guide:
Look for a dropdown button with text like "Example Presentation" next to the PPT Agent logo.

3Create New Presentation

Click the dropdown to open it, then click the "Create Presentation" button from the menu.

What you'll see:
A dialog modal will appear with form fields for creating your presentation.

4Fill Out Presentation Details

Presentation Name *

Required. Choose a descriptive name for your presentation.

Example: "Q4 Product Roadmap"
Description (Optional)

Brief description of your presentation's purpose.

Example: "Company strategy and upcoming product launches"

5Create and Verify

Click the "Create" button to create your presentation. The dialog will close and you'll be automatically switched to your new presentation.

Success indicators:
  • • The dropdown now shows your presentation name
  • • You'll see 0 slides (empty presentation ready for content)
  • • The presentation selector lists your new presentation under "Your Presentations"

Method 2: REST API

API Endpoint

POST/api/presentations

Creates a new presentation programmatically

Request Format

Content-Type: application/json
Required Body Parameters:
  • name(string, required) Presentation name
Optional Body Parameters:
  • description(string, optional) Presentation description
  • theme(string, optional) Theme name (defaults to "default")

Example Requests

1cURL Command

curl -X POST http://localhost:3000/api/presentations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Presentation",
    "description": "Created via REST API",
    "theme": "dark"
  }'

2JavaScript/Node.js

const response = await fetch('http://localhost:3000/api/presentations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'API Generated Presentation',
    description: 'Automated presentation creation',
    theme: 'default'
  })
});

const presentation = await response.json();
console.log('Created presentation:', presentation.id);

3Python

import requests

response = requests.post(
    'http://localhost:3000/api/presentations',
    json={
        'name': 'Python Generated Presentation',
        'description': 'Created with Python requests',
        'theme': 'default'
    }
)

presentation = response.json()
print(f"Created presentation: {presentation['id']}")

Response Format

Success Response (201 Created):
{
  "id": "my-api-presentation",
  "name": "My API Presentation",
  "description": "Created via REST API",
  "theme": "dark",
  "created": "2024-01-12T23:17:31.000Z",
  "modified": "2024-01-12T23:17:31.000Z",
  "slideCount": 0
}
Error Response (400 Bad Request):
{
  "error": "Presentation name is required"
}

What Happens Next

Presentation Structure

Your presentation is stored in the filesystem with this structure:

presentations/
└── my-presentation/
    ├── config.json          # Presentation metadata
    └── slides/              # Your .mdx slide files go here
        ├── 01-intro.mdx
        ├── 02-content.mdx
        └── ...

Next Steps

  • Add slides using MDX files in the slides/ directory
  • Switch between presentations using the dropdown selector
  • Manage presentations through the web interface
  • Validate your slides with npm run validate

Slide Formatting Guide

Learn how to format your slides using PPT Agent's slide types and MDX components. This guide covers all available formatting options for creating beautiful presentations.

Table of Contents

Hero Slide

Purpose: Large, impactful title slides with animated backgrounds.

Properties:
  • type: "hero" (required)
  • title: Main heading text (required)
  • subtitle: Smaller subtitle text (optional)
Example:
---
type: hero
title: "Welcome to PPT Agent"
subtitle: "The future of presentations"
---
Visual: Displays a large animated title with gradient text effects and subtle background animations.

Timeline Slide

Purpose: Display chronological events or milestones with a curved timeline visualization.

Properties:
  • type: "timeline" (required)
  • title: Timeline title (required)
  • subtitle: Timeline subtitle (optional)
  • points: Array of timeline points (required)
    • date: Date string (e.g., "2024 Q1", "Jan 15, 2024")
    • title: Event title
Example:
---
type: timeline
title: "Product Roadmap"
subtitle: "2024 Development Timeline"
points:
  - date: "Q1 2024"
    title: "MVP Launch"
  - date: "Q2 2024"
    title: "User Feedback Integration"
  - date: "Q3 2024"
    title: "Advanced Features"
---
Visual: Animated curved line connecting dated points with labels positioned alternately above/below the timeline.

Messages Slide

Purpose: Showcase key messages or features in card format with icons.

Properties:
  • type: "messages" (required)
  • title: Section title (required)
  • cards: Array of message cards (required)
    • number: Display number (e.g., "01", "1")
    • title: Card title
    • icon: Lucide React icon name
    • description: Card description text
Example:
---
type: messages
title: "Why Choose Us"
cards:
  - number: "01"
    title: "Lightning Fast"
    icon: "zap"
    description: "Built for performance with modern technologies"
  - number: "02"
    title: "Secure by Design"
    icon: "shield"
    description: "Enterprise-grade security from day one"
---
Visual: Three cards in a grid layout with hover animations, numbered badges, and icons.

Stats Slide

Purpose: Display metrics and KPIs with animated counters and progress bars.

Properties:
  • type: "stats" (required)
  • title: Stats section title (required)
  • subtitle: Section subtitle (optional)
  • stats: Array of stat items (required)
    • value: Number or string value
    • label: Stat label
    • prefix: Text before value (e.g., "$")
    • suffix: Text after value (e.g., "%", "+")
  • layout: Layout style (optional, default: "grid")
    • "grid": 4-column grid with card backgrounds
    • "row": Single row layout
    • "columns": 2-column vertical layout
Example:
---
type: stats
title: "2024 Performance"
subtitle: "Key Metrics"
layout: "grid"
stats:
  - value: 1250000
    label: "Active Users"
    suffix: "+"
  - value: 99.9
    label: "Uptime"
    suffix: "%"
---
Visual: Animated counters with progress bars automatically shown for values 0-100%.

Quote Slide

Purpose: Display testimonials or inspirational quotes with author attribution.

Properties:
  • type: "quote" (required)
  • quote: Quote text (required)
  • author: Author name (optional)
  • title: Author title (optional)
  • company: Author company (optional)
  • avatar: Avatar image URL (optional)
  • background: Background style (optional, default: "gradient")
    • "gradient": Multi-color gradient
    • "minimal": Black background
    • "accent": Purple accent gradient
Example:
---
type: quote
quote: "PPT Agent transformed how we present to stakeholders."
author: "Sarah Chen"
title: "VP of Product"
company: "TechCorp Inc."
background: "accent"
---
Visual: Large centered quote with author info in a card format, decorative quote marks, and background styling.

Terminal Slide

Purpose: Showcase code examples, commands, and technical demonstrations.

Properties:
  • type: "terminal" (required)
  • title: Terminal section title (required)
  • commands: Array of command/code blocks (required)
    • prompt: Command prompt (optional, defaults to >)
    • command: Code or command text (required)
    • output: Command output (optional)
    • language: Programming language (optional)
  • theme: Syntax highlighting theme (optional, default: "dark")
    • "dark": Dark theme
    • "light": Light theme
    • "monokai": Monokai theme
Example:
---
type: terminal
title: "Getting Started"
theme: "dark"
commands:
  - prompt: "~"
    command: "npm install vision-deck"
    output: "added 42 packages in 3.2s"
  - command: |
      import { createDeck } from 'vision-deck'
      const deck = createDeck({
        slides: ['./slides/*.mdx']
      })
    language: "typescript"
---
Visual: Terminal-style windows with syntax highlighting, copy buttons, and collapsible output sections.

MDX Components

MDX components can be used within slide content for rich formatting and interactive elements.

Callout

Purpose: Highlight important information with styled boxes.

Properties:
  • type: Callout style (optional, default: "info") - "info", "warning", "success", "error", "tip"
  • title: Callout title (optional)
Code Example:
<Callout type="warning" title="Important">
  This action cannot be undone.
</Callout>
Visual Examples:
Information
This is an informational callout with helpful details.
Important Warning
This action cannot be undone. Make sure to backup your data first.
Successfully deployed to production!
Error
Something went wrong. Please try again.
Pro Tip
Use keyboard shortcuts to speed up your workflow.

Highlight

Purpose: Highlight important text with colored backgrounds.

Properties:
  • color: Highlight color (optional, default: "yellow") - "yellow", "green", "blue", "pink", "purple"
Code Example:
This feature is <Highlight color="green">new</Highlight>!
Visual Examples:

This feature is highlighted in yellow by default.

This is highlighted in green for success.

This shows blue highlighting for information.

This uses pink highlighting for emphasis.

This demonstrates purple highlighting for special content.

Badge

Purpose: Display status indicators or labels.

Properties:
  • variant: Badge style (optional, default: "default") - "default", "success", "warning", "error", "outline"
  • size: Badge size (optional, default: "md") - "sm", "md", "lg"
Code Example:
<Badge variant="success" size="sm">New</Badge>
Visual Examples:
DefaultSuccessWarningErrorOutline
SmallMediumLarge

Progress

Purpose: Show progress bars with animated fill.

Properties:
  • value: Current progress value (required)
  • max: Maximum value (optional, default: 100)
  • label: Progress bar label (optional)
  • showValue: Show percentage (optional, default: true)
  • size: Bar thickness (optional, default: "md") - "sm", "md", "lg"
  • color: Bar color (optional, default: "white") - "white", "green", "blue", "purple"
Code Example:
<Progress value={75} label="Completion" color="green" />
Visual Examples:
Completion75%
Upload Progress90%
25%

Code

Purpose: Inline code formatting.

Properties:
  • language: Programming language (optional)
Code Example:
Use the <Code>npm install</Code> command.
Visual Examples:

Use the npm install command to get started.

You can also highlight function names and variables inline.

Counter

Purpose: Animated number counters.

Properties:
  • value: Target number (required)
  • duration: Animation duration in seconds (optional, default: 1)
  • prefix: Text before number (optional)
  • suffix: Text after number (optional)
Code Example:
<Counter value={1500000} prefix="$" suffix="+" />
Visual Examples:
$0+Revenue
0 usersActive Users
0%Uptime

AnimatedNumber

Purpose: Precise animated numbers with decimal support.

Properties:
  • value: Target number (required)
  • decimals: Decimal places (optional, default: 0)
  • duration: Animation duration in seconds (optional, default: 1)
Code Example:
<AnimatedNumber value={3.14159} decimals={2} />
Visual Examples:
0.00Pi (2 decimals)
0.0Temperature
0Whole number

Step

Purpose: Numbered step-by-step instructions.

Properties:
  • number: Step number (required)
  • title: Step title (required)
  • active: Highlight as active step (optional, default: false)
Code Example:
<Step number={1} title="Install Dependencies">
  Run `npm install` to install packages.
</Step>
Visual Examples:
1

Install Dependencies

Run `npm install` to install all required packages.
2

Configure Settings

Update your configuration file with API keys.
3

Start Development Server

Run `npm run dev` to start the development server.

AccordionItem

Purpose: Collapsible content sections.

Properties:
  • title: Accordion title (required)
  • defaultOpen: Start expanded (optional, default: false)
Code Example:
<AccordionItem title="Advanced Configuration">
  Detailed configuration options go here.
</AccordionItem>
Visual Examples:
Common issues and their solutions:
• Check your internet connection
• Verify API credentials
• Clear browser cache
• Restart the development server

Best Practices

Slide Type Selection

  • Hero: Use for major section headers or presentation titles
  • Timeline: Perfect for roadmaps, project phases, or historical events
  • Messages: Great for feature highlights, benefits, or key points
  • Stats: Ideal for metrics, KPIs, and quantitative achievements
  • Quote: Best for testimonials, mission statements, or inspirational content
  • Terminal: Use for code demos, technical instructions, or CLI workflows

MDX Component Usage

  • Callout: Reserve for important notices, warnings, or tips
  • Highlight: Use sparingly to emphasize key terms or phrases
  • Badge: Perfect for status indicators, labels, or categories
  • Progress: Show completion status or progress toward goals
  • Counter/AnimatedNumber: Animate important metrics or statistics
  • Step: Break down complex processes into digestible steps
  • AccordionItem: Organize detailed information without cluttering the slide
Performance
  • • Limit animated counters to 4-6 per stats slide
  • • Use progress bars only for values 0-100%
  • • Keep terminal command arrays to 3-5 items
  • • Test animations on target devices
Accessibility
  • • Ensure sufficient color contrast
  • • Provide alt text for quote slide images
  • • Use semantic heading structure
  • • Test keyboard navigation
File Organization
  • • Use numbered prefixes (01-, 02-, etc.)
  • • Keep slide content focused
  • • Validate with npm run validate
  • • Test presentation flow

Tips & Best Practices

Naming Conventions

  • • Use descriptive, human-readable names
  • • Names are converted to URL-safe IDs automatically
  • • Special characters are removed, spaces become hyphens
  • • Example: "Q4 Roadmap 2024" → "q4-roadmap-2024"

Troubleshooting

  • • Empty name: Presentation name cannot be blank
  • • Duplicate name: Choose a unique name
  • • API errors: Check Content-Type header is set correctly
  • • Server not running: Ensure PPT Agent is started with npm run dev

New Slide Templates Guide

PPT Agent now includes 26 additional slide templates organized into four categories: Clean & Minimal, Visual Impact, Interactive & Motion, and Content-Focused. Each template is designed for specific use cases with built-in animations and responsive layouts.

Phase 1: Clean & Minimal

These templates emphasize clarity, whitespace, and simplicity. Perfect for corporate presentations, educational content, and any situation where the message should take center stage.

Split Slide

Best for: Product comparisons, before/after scenarios, feature explanations with visuals

  • • Place impactful images on one side
  • • Use overlayText for captions on images
  • • imagePosition controls left/right layout
  • • Great for storytelling with visuals

Two Column Slide

Best for: Pros/cons lists, comparisons, parallel concepts

  • • Each column has title, content, and optional icon
  • • Animated divider line between columns
  • • Use icons to reinforce the message
  • • Keep content balanced between sides

Big Statement Slide

Best for: Key takeaways, bold claims, punchy headlines

  • • Uses massive typography (up to 9rem)
  • • Optional highlight badge for emphasis
  • • Minimal supporting text recommended
  • • Perfect for "aha!" moments

Minimal Slide

Best for: Quotes, single ideas, dramatic pauses

  • • Single focused message with generous whitespace
  • • Configurable alignment (left/center/right)
  • • Optional caption below main text
  • • Use sparingly for maximum impact

Bullets Slide

Best for: Feature lists, benefits, key points

  • • Animated stagger reveal for each bullet
  • • Optional text highlighting within bullets
  • • Hover effects on bullet points
  • • Best with 3-6 bullet points

Numbered Slide

Best for: Processes, workflows, step-by-step guides

  • • Large numbered badges with animations
  • • Each step has number, title, description
  • • Visual connector lines between steps
  • • Great for onboarding or tutorials

Phase 2: Visual Impact

These templates leverage imagery, graphics, and visual storytelling. Ideal for creative presentations, portfolios, product launches, and any content where visuals drive the narrative.

Fullscreen Slide

Best for: Hero images, dramatic openings, emotional storytelling

  • • Full-bleed background image with overlay
  • • Overlay options: dark, light, or gradient
  • • Text position: top, center, or bottom
  • • Ken Burns zoom effect on image

Gallery Slide

Best for: Portfolio showcases, product collections, visual storytelling

  • • Three layout modes: grid, masonry, featured
  • • Hover effects reveal captions/titles
  • • Staggered animation on load
  • • Supports 4-12 images per slide

Highlight Slide

Best for: Feature announcements, product spotlights, key differentiators

  • • Large image with supporting bullet points
  • • Optional badge overlay on image
  • • Points animate in with stagger
  • • Great for "New Feature" announcements

Showcase Slide

Best for: App demos, product screenshots, UI walkthroughs

  • • Device frames: laptop, phone, tablet, browser
  • • Annotation callouts with positioning
  • • Browser chrome simulation available
  • • Perfect for SaaS product demos

Diagram Slide

Best for: System architecture, workflows, relationships

  • • Node-based diagram with connections
  • • Animated path drawing between nodes
  • • Position nodes with x,y coordinates
  • • Great for technical presentations

Infographic Slide

Best for: Statistics, metrics, data visualization

  • • Icon + value + label format
  • • Layouts: horizontal, vertical, radial
  • • Custom colors per item
  • • Hover scale animations

Phase 3: Interactive & Motion

These templates feature advanced animations and interactivity. Use them to create memorable moments, engage your audience, and add dynamic energy to your presentations.

Reveal Slide

Best for: Quizzes, progressive disclosure, building suspense

  • • Three modes: click, sequential, auto
  • • Click items to reveal content
  • • Icon support for visual cues
  • • Great for interactive Q&A sections

Motion Slide

Best for: Energetic transitions, dynamic content, attention-grabbing moments

  • • Animation types: fade, slide, scale, rotate
  • • Staggered timing with delay parameter
  • • Background effects: particles, waves, none
  • • Hover interactions on elements

Parallax Slide

Best for: Depth effects, immersive experiences, layered storytelling

  • • Multiple layers with different scroll speeds
  • • Creates 3D depth effect
  • • Each layer can have its own image
  • • Great for dramatic visual impact

Morph Slide

Best for: Transformations, adaptability messaging, fluid concepts

  • • SVG shape morphing animation
  • • Shapes: circle, square, triangle, star, diamond, hexagon
  • • Synchronized text changes
  • • Auto-advances every 3 seconds

Counter Slide

Best for: Live metrics, KPIs, impressive statistics

  • • Animated number counting effect
  • • Prefix/suffix support (%, +, $, etc.)
  • • Optional progress bar charts
  • • Custom colors per counter
  • • Supports large numbers with proper formatting

Phase 4: Content-Focused

These templates are designed for specific content types like testimonials, pricing, and team info. They include purpose-built layouts and components for common presentation needs.

Testimonial Slide

Best for: Customer quotes, social proof, reviews

  • • Carousel or grid layout options
  • • Star ratings support
  • • Avatar images with fallback initials
  • • Navigation arrows and indicators

Team Slide

Best for: Team introductions, about us sections, org charts

  • • Grid layout with hover effects
  • • Avatar support with fallback initials
  • • Social links (Twitter, LinkedIn, GitHub)
  • • Optional bio text for each member

Pricing Slide

Best for: Product pricing, plan comparisons, tiers

  • • Up to 3 pricing tiers per slide
  • • Highlighted tier gets visual emphasis
  • • Feature lists with checkmarks
  • • CTA buttons on each tier

Features Slide

Best for: Product features, service offerings, capabilities

  • • Icon + title + description format
  • • Grid or list layout options
  • • Hover lift animations
  • • Best with 4-8 features

CTA Slide

Best for: Call-to-action, signup prompts, final slides

  • • High-impact headline typography
  • • Prominent CTA button with arrow
  • • Background styles: gradient, solid, or image
  • • Secondary text for disclaimers
  • • Perfect for presentation closing

Quick Reference: Choosing the Right Template

Need Clarity?

Use Clean & Minimal templates:

  • • Big Statement for key takeaways
  • • Minimal for single powerful ideas
  • • Bullets for feature lists
  • • Numbered for processes

Need Visual Impact?

Use Visual Impact templates:

  • • Fullscreen for dramatic images
  • • Gallery for portfolios
  • • Showcase for product demos
  • • Infographic for data

Need Engagement?

Use Interactive & Motion templates:

  • • Reveal for interactive Q&A
  • • Motion for energetic moments
  • • Counter for impressive stats
  • • Morph for transformation stories

Need Specific Content?

Use Content-Focused templates:

  • • Testimonial for social proof
  • • Team for introductions
  • • Pricing for plan comparisons
  • • CTA for conversion moments

Need help with creating slides? Check out the example presentation or visit our GitHub repository for more documentation.