mdeck 0.12.0

A markdown-based presentation tool
mdeck-0.12.0 is not a library.

What is MDeck?

MDeck turns standard markdown files into polished presentations. No proprietary formats, no complex setup — just write markdown and present.

  • Any .md file is instantly presentable — layout is inferred from content structure
  • 16 visualization types — bar charts, diagrams, Gantt charts, word clouds, and more
  • AI image generation — generate slide images from text prompts
  • Built in Rust — fast, lightweight, GPU-accelerated rendering
  • Export to PNG — share slides without the tool

Installation

Homebrew (macOS / Linux)

brew install mklab-se/tap/mdeck

Pre-built binaries

Download from GitHub Releases — available for macOS (Intel + ARM), Linux, and Windows.

Cargo

cargo install mdeck

Build from source

git clone https://github.com/mklab-se/mdeck.git
cd mdeck
cargo install --path crates/mdeck

Quick Start

# Present a markdown file
mdeck slides.md

# Export slides as PNG images
mdeck export slides.md

# Show all commands
mdeck --help

Write a file called talk.md:

---
title: "My Talk"
@theme: dark
---

# Welcome

This is my first MDeck presentation.

---

## Key Points

- Write in standard markdown
- Slides are separated by `---`
- Layout is inferred automatically

---

## Architecture

​```@diagram
- Client -> Server: requests
- Server -> Database: queries
- Database -> Server: results
​```

Then present it: mdeck talk.md

Features

Automatic Layout Inference

MDeck detects what kind of slide you're writing and picks the best layout:

Content Layout
Heading + subtitle Title
Lone heading Section divider
Heading + bullet list Bullet
Heading + code block Code
Blockquote + attribution Quote
Single image Full-screen image
Bullets + image Split layout
+++ separator Two-column
@diagram code block Diagram
@barchart, @piechart, etc. Visualization

Override with @layout: name when needed.

Visualizations

Write data visualizations directly in markdown using fenced code blocks:

Type Tag Example
Bar chart @barchart - Python: 48
Line chart @linechart - Revenue: 100, 150, 200
Pie chart @piechart - Frontend: 35%
Donut chart @donut - Complete: 78
Stacked bar @stackedbar - Product A: 40, 45, 50
Scatter plot @scatter - Alice: 80, 90
Radar chart @radar - Speed: 9, 7, 5, 3
Funnel @funnel - Visitors: 10000
KPI cards @kpi - Revenue: $4.2M (trend: +12%)
Progress bars @progress - Design: 100%
Timeline @timeline - 2024: Project launch
Word cloud @wordcloud - AI (size: 50)
Venn diagram @venn - Set A & Set B: Overlap
Org chart @orgchart - CEO -> CTO
Gantt chart @gantt - Design: 8d, after Research
Diagram @diagram - Client -> Server

All visualizations support progressive reveal with + markers.

Diagrams

Architecture and flow diagrams from text:

​```@diagram
- Browser   (icon: browser,  pos: 1,1)
- API       (icon: api,      pos: 2,1)
- Database  (icon: database, pos: 2,2)

- Browser -> API: requests
- API -> Database: queries
​```

Features: grid positioning, 20+ built-in icons, 5 arrow types (->, <-, <->, --, -->), labeled connections, and AI-generated custom icons.

Themes

Built-in themes: light, dark, solarized, dracula, nord, gruvbox, and more.

Set globally in frontmatter or per-slide:

---
@theme: dark
@transition: spatial
---

Transitions

Smooth animated transitions between slides: fade, slide, spatial, and none. Cycle with T during presentation.

Slide Splitting

Three mechanisms create slide breaks (all combine):

  1. --- separator with blank lines on both sides
  2. Three blank lines between content
  3. Heading inference — headings automatically start new slides

Smart heading inference: if your file has one # title and uses ## for sections, both levels split. Control explicitly with @slide-level: 2 in frontmatter.

AI Features

MDeck integrates AI for image and icon generation. Configure with mdeck ai enable.

Generate Images for a Presentation

Add image placeholders to your markdown:

## African Savanna

- Home to 54 countries
- The Sahara is the size of the United States

![A sweeping savanna at golden hour with acacia trees](image-generation)

Then generate all images at once:

mdeck ai generate slides.md

MDeck scans for image-generation markers, generates images using AI, saves them to an images/ directory, and rewrites your markdown with the actual file paths.

Style Control

Control the visual style of generated images:

---
@image-style: "Cinematic photography, vivid colors, dramatic lighting"
@icon-style: "Clean minimalist icon, subtle 3D feel"
---

Or manage named styles:

mdeck ai style add Cinematic "Vivid colors, dramatic lighting, sweeping vistas"
mdeck ai style set-default Cinematic
mdeck ai style list

Ad-Hoc Image Generation

Generate individual images from the command line:

mdeck ai generate-image --prompt "A futuristic cityscape at sunset"
mdeck ai generate-image --prompt "A database server" --icon --output db.png

Diagram Icons

Generate custom icons for diagram nodes:

​```@diagram
- Gateway (icon: generate-image, prompt: "An API gateway router")
- Auth    (icon: generate-image, prompt: "A security lock shield")
​```

Run mdeck ai generate to create and cache the icons.

Commands

mdeck <file.md>              # Launch presentation
mdeck <file.md> --check      # Validate presentation (exit 1 if warnings)
mdeck export <file.md>       # Export slides as PNG images (1920x1080)
mdeck export <file.md> --width 3840 --height 2160  # Custom resolution
mdeck spec                   # Print full format specification
mdeck spec --short           # Print quick reference card
mdeck completion <shell>     # Generate shell completions
mdeck config show            # Display current settings
mdeck config set <key> <val> # Set config value
mdeck ai                     # Show AI status
mdeck ai enable              # Enable AI features
mdeck ai disable             # Disable AI features
mdeck ai test                # Test AI integration
mdeck ai config              # Open AI config in editor
mdeck ai generate <file.md>  # Generate all AI images in a presentation
mdeck ai generate-image      # Generate a single image from a prompt
mdeck ai style list          # List defined image styles
mdeck ai style add <n> <d>   # Add a named style
mdeck ai style set-default   # Set the default image style

Keyboard Controls

Key Action
Space / N / Right Next slide
P / Left Previous slide
Up / Down Scroll overflowed content
G Grid overview
D Cycle theme
T Cycle transition
F Toggle fullscreen
H Toggle HUD
. Blackout screen
Esc Esc Quit

Shell Completions

# Static completions
mdeck completion bash > ~/.bash_completion.d/mdeck
mdeck completion zsh > ~/.zfunc/_mdeck

# Dynamic completions (recommended)
source <(COMPLETE=bash mdeck)
source <(COMPLETE=zsh mdeck)

Documentation

  • Gallery — Visual showcase of all layouts and visualizations
  • Format Specification — Complete reference for the MDeck markdown format (also available via mdeck spec)
  • Changelog — Release history and what's new

The format spec is embedded in the binary and available via mdeck spec. It covers all slide layouts, directives, visualization syntax, diagram features, and keyboard shortcuts.

Development

cargo build              # Build
cargo test --workspace   # Run tests
cargo clippy --workspace -- -D warnings  # Lint (CI-enforced)
cargo fmt --all -- --check               # Format check (CI-enforced)
cargo run -p mdeck       # Run the app

License

MIT