<p align="center">
<img src="https://raw.githubusercontent.com/mklab-se/mdeck/main/media/mdeck-horizontal.png" alt="mdeck" width="600">
</p>
<h1 align="center">MDeck</h1>
<p align="center">
Stunning presentations from markdown.<br>
Write content. MDeck handles the rest.
</p>
<p align="center">
<a href="https://github.com/mklab-se/mdeck/actions/workflows/ci.yml"><img src="https://github.com/mklab-se/mdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://crates.io/crates/mdeck"><img src="https://img.shields.io/crates/v/mdeck.svg" alt="crates.io"></a>
<a href="https://github.com/mklab-se/mdeck/releases/latest"><img src="https://img.shields.io/github/v/release/mklab-se/mdeck" alt="GitHub Release"></a>
<a href="https://github.com/mklab-se/homebrew-tap/blob/main/Formula/mdeck.rb"><img src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmklab-se%2Fhomebrew-tap%2Fmain%2FFormula%2Fmdeck.rb&search=%5Cd%2B%5C.%5Cd%2B%5C.%5Cd%2B&label=homebrew&prefix=v&color=orange" alt="Homebrew"></a>
<a href="https://github.com/mklab-se/mdeck/blob/main/LICENSE.md"><img src="https://img.shields.io/crates/l/mdeck.svg" alt="License"></a>
</p>
<p align="center">
<a href="GALLERY.md"><strong>Gallery</strong></a> ·
<a href="crates/mdeck/doc/mdeck-spec.md"><strong>Format Spec</strong></a> ·
<a href="CHANGELOG.md"><strong>Changelog</strong></a>
</p>
---
## What is MDeck?
MDeck creates stunning presentations from standard markdown files. No proprietary formats, no complex setup — just write markdown and present beautifully.
- **Any `.md` file is instantly presentable** — intelligent layout inference picks the right slide design from your content structure: title slides, bullet lists, code blocks, quotes, images, tables, and more
- **Built-in visualizations** — architecture diagrams, Gantt charts, word clouds, bar/line/pie charts, KPI dashboards, org charts, timelines, radar charts, scatter plots, Venn diagrams, and more — all from simple text in your markdown
- **AI-powered presentation creation** — turn any content into a polished presentation with `mdeck ai create`. Feed it a PDF, DOCX, markdown file, or just a text prompt — MDeck analyzes the content, identifies key points, and generates a complete presentation with speaker notes, visualizations, and image placeholders. Your source material becomes a compelling talk in seconds
- **AI-native** — since presentations are just markdown, any AI can help you write them. But MDeck also has AI built directly in: generate images and icons in your chosen style, right from the command line. Your slides, your aesthetic
- **Built in Rust** — fast, lightweight, GPU-accelerated rendering with smooth transitions and animations
<p align="center">
<img src="media/gallery/slide-08.png" width="45%">
<img src="media/gallery/slide-22.png" width="45%">
</p>
<p align="center">
<img src="media/gallery/slide-25.png" width="45%">
<img src="media/gallery/slide-26.png" width="45%">
</p>
<p align="center"><em>See the full <a href="GALLERY.md">Gallery</a> for all layouts and visualization types.</em></p>
---
## Installation
### Homebrew (macOS / Linux)
```bash
brew install mklab-se/tap/mdeck
```
### Pre-built binaries
Download from [GitHub Releases](https://github.com/mklab-se/mdeck/releases) — available for macOS (Intel + ARM), Linux, and Windows.
### Cargo
```bash
cargo install mdeck
```
### Build from source
```bash
git clone https://github.com/mklab-se/mdeck.git
cd mdeck
cargo install --path crates/mdeck
```
---
## Quick Start
```bash
# 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`:
```markdown
---
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
```@architecture
- 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:
| 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 |
| `@architecture` code block | Architecture diagram |
| `@barchart`, `@piechart`, etc. | Visualization |
Override with `@layout: name` when needed.
### Visualizations
Write data visualizations directly in markdown using fenced code blocks:
| 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` |
| Architecture | `@architecture` | `- Client -> Server` |
| Git graph | `@gitgraph` | `- branch develop from main` |
All visualizations support progressive reveal with `+` markers.
### Architecture Diagrams
Architecture and flow diagrams from text:
```markdown
```@architecture
- 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**, and **nord**. Cycle with `Shift+T` during presentation.
Set globally in frontmatter or per-slide:
```yaml
---
@theme: dark
@transition: spatial
---
```
### Speaker Notes
Add presenter-only notes to any slide with the `???` separator:
```markdown
# Key Decision
- We chose microservices for team autonomy
- Event-driven for loose coupling
???
Emphasize that this wasn't about scale — it was about letting teams
ship independently. Ask: "How many of you have migrated from a monolith?"
```
Notes are parsed but never shown in the presentation — they're designed to help the presenter understand each slide's intent and deliver it effectively. When MDeck generates presentations with AI, every slide includes detailed speaker notes explaining what to say and how to present it.
### 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 intelligent presentation creation and image generation. Configure with `mdeck ai enable`.
### Create Presentations from Anything
Turn any content into a polished presentation — text prompts, documents, PDFs, DOCX files, or piped input:
```bash
# From a text prompt
mdeck ai create --input "A presentation about Git Flow for software teams" --output git-flow/
# From a PDF report
mdeck ai create --input company-report.pdf --output company-report.md
# From a Word document
mdeck ai create --input camera-manual.docx --output camera-manual.md
# From piped input
# Interactive mode — MDeck asks about audience, purpose, and key points
mdeck ai create -i --input environment-report.md --output presentation/
# With audience/purpose context
mdeck ai create --input a-book-on-hobbits.md --output hobbits.md \
--prompt "For 10-year-old children, focusing on the adventures"
```
MDeck doesn't just dump content onto slides — it **analyzes** your source material, identifies key points, and creates a concise, engaging presentation designed to support a presenter. Each slide includes detailed speaker notes explaining the intent and suggested delivery approach. The source material serves as the detailed handout; the presentation tells the story.
The generation pipeline:
1. **Extract** — reads text from any supported format (PDF, DOCX, markdown, plain text)
2. **Analyze** — AI identifies key points, structure, and visualization opportunities
3. **Generate** — creates complete mdeck-format slides with speaker notes, visualizations, and image placeholders
4. **Post-process** — validates the output and identifies opportunities for MDeck visualizations
### Generate Images for a Presentation
Add image placeholders to your markdown:
```markdown
## African Savanna
- Home to 54 countries
- The Sahara is the size of the United States
```
Then generate all images at once:
```bash
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:
```yaml
---
@image-style: "Cinematic photography, vivid colors, dramatic lighting"
@icon-style: "Clean minimalist icon, subtle 3D feel"
---
```
Or manage named styles:
```bash
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:
```bash
mdeck ai generate-image --prompt "A futuristic cityscape at sunset"
mdeck ai generate-image --prompt "A database server" --icon --output db.png
```
### Architecture Diagram Icons
Generate custom icons for architecture diagram nodes:
```markdown
```@architecture
- 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
```bash
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 status # Show AI status (explicit)
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 create # Create a presentation from content using AI
mdeck ai create --input X # Create from file or text prompt
mdeck ai create -i # Interactive mode (asks questions first)
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
mdeck ai skill # AI agent skill setup guide
mdeck ai skill --emit # Output skill file for Claude Code
mdeck ai skill --reference # Output full reference for AI agents
```
### Keyboard Controls
| Space / N / Right | Next slide |
| P / Left | Previous slide |
| Up / Down | Scroll overflowed content |
| G | Grid overview |
| Shift+T | Cycle theme |
| T | Cycle transition |
| F | Toggle fullscreen |
| H | Toggle HUD |
| `.` | Blackout screen |
| Esc Esc | Quit |
### Shell Completions
```bash
# 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](GALLERY.md)** — Visual showcase of all layouts and visualizations
- **[Format Specification](crates/mdeck/doc/mdeck-spec.md)** — Complete reference for the MDeck markdown format (also available via `mdeck spec`)
- **[Changelog](CHANGELOG.md)** — 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
```bash
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