How AgentPreso Works

AgentPreso is built around one idea: a presentation is a single markdown file. This page explains how the system turns that file into rendered slides, and how the pieces fit together.

The markdown file

Everything starts with a .md file. It contains your slide content in standard markdown, a YAML frontmatter block that says which theme to use, and optional chart/diagram code blocks:

---
agentpreso:
  theme: corporate
---

# Title Slide

---

## Slide with a chart

```chart
type: bar
data:
  labels: [Q1, Q2, Q3]
  datasets:
    - label: Revenue
      data: [10, 15, 20]

This file is valid markdown that any editor can display. And it's plain text that AI agents can read, write, and edit.

## Three interfaces, one system

AgentPreso exposes the same functionality through three interfaces:

- **CLI** (`agentpreso`) — a standalone binary for your terminal. Create, edit, preview, render, and sync decks.
- **REST API** (`api.agentpreso.com`) — programmatic access to decks, themes, assets, and rendering.
- **MCP** (`api.agentpreso.com/mcp`) — Model Context Protocol endpoint that AI agents (like Claude) use to manage presentations through conversation.

All three share the same backend. A deck created through MCP can be pulled with the CLI, or fetched via the API.

## What happens when you render

When you run `agentpreso render deck.md --format pdf`, here's what happens:

1. **Parse frontmatter** — extract the theme name, brand overrides, and variable defaults
2. **Substitute variables** — replace `{{placeholder}}` tokens in the slide body with values from `--vars` files and `--var` flags (frontmatter defaults are lowest priority)
3. **Resolve the theme** — look up the named theme (user custom first, then built-in, then fall back to `minimal`) and load its CSS
4. **Apply brand overrides** — if `agentpreso.brand` has CSS variable overrides, layer them on top of the theme CSS
5. **Render with the SlimEngine** — processes chart blocks (rendered via ECharts), mermaid blocks (rendered server-side as SVG), and the layout system
6. **Generate output** — HTML (self-contained), PDF (via headless browser), or PPTX (via Pandoc conversion)
7. **Inject logos** — if the theme has logo configuration, logos are positioned on each slide according to the placement rules

## Cloud storage

The server stores three things:

- **Decks** — your presentations (markdown content + metadata), in a D1 (SQLite) database
- **Themes** — built-in and custom themes (CSS + manifest), in the same database
- **Assets** — images and files referenced by `asset://` URIs, in R2 (object storage)

When you `push` a deck, the CLI uploads the markdown and any referenced assets. When you `pull`, it downloads the latest version. The server handles rendering (PDF/PPTX generation requires a headless browser) so your local machine doesn't need Chrome or Pandoc installed.

## Themes

Themes are the visual layer. They define colors, fonts, and how each layout class renders. The system separates concerns:

- **Base CSS** — shared layout definitions (grids, positioning) that all themes inherit
- **Theme CSS** — colors, fonts, and visual styling specific to each theme
- **Brand overrides** — per-deck CSS variable overrides from frontmatter

This means layout behavior is consistent across themes — `two-col` always creates two columns — but the colors, fonts, and decorative styles change with the theme.

## Template variables

The `{{variable}}` system enables reusable decks. A sales proposal deck can have `{{company}}`, `{{deal_size}}`, and `{{revenue_data}}` placeholders that get filled in at render time. This is especially powerful with AI agents — an agent can create a deck once and render it with different data for each client.

Variables are substituted in the slide body, chart blocks, and diagram blocks — but never in frontmatter, regular code blocks, or inline code.

## Authentication

Two authentication flows share the same user account:

- **Dashboard** (app.agentpreso.com) — email/password sign-in with cookie sessions
- **CLI and MCP** — API keys (`ap_...`) stored locally or passed in headers

API keys are created in the dashboard and can be revoked at any time.

## Related

- [Themes](/docs/themes) — built-in theme catalog and customization
- [Build Your First Presentation](/docs/getting-started) — hands-on tutorial
- [Markdown Format Reference](/docs/markdown-format) — complete syntax