Vision Deck Guide

Learn how to create beautiful presentations using Vision Deck's web interface and API

Quick Start

Vision Deck 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 Vision Deck

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

Expected result:

You'll see the Vision Deck interface with "Vision Deck" 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 Vision Deck 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 Vision Deck's slide types and MDX components. This guide covers all available formatting options for creating beautiful presentations.

MDX Components

• Callout
• Highlight
• Badge
• Progress
• Code
• Counter
• AnimatedNumber
• Step
• AccordionItem

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 Vision Deck"
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: "Vision Deck 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:

Install Dependencies

Run `npm install` to install all required packages.

Configure Settings

Update your configuration file with API keys.

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 Vision Deck is started with npm run dev

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

Vision Deck Guide

Quick Start

Method 1: Web App Interface

1Access Vision Deck

2Open Presentation Selector

3Create New Presentation

4Fill Out Presentation Details

5Create and Verify

Method 2: REST API

API Endpoint

Request Format

Example Requests

1cURL Command

2JavaScript/Node.js

3Python

Response Format

What Happens Next

Presentation Structure

Next Steps

Slide Formatting Guide

Table of Contents

Slide Types

MDX Components

Hero Slide

Timeline Slide

Messages Slide

Stats Slide

Quote Slide

Terminal Slide

MDX Components

Callout

Highlight

Badge

Progress

Code

Counter

AnimatedNumber

Step

Install Dependencies

Configure Settings

Start Development Server

AccordionItem

Best Practices

Slide Type Selection

MDX Component Usage

Performance

Accessibility

File Organization

Tips & Best Practices

Naming Conventions

Troubleshooting