Turn one Markdown file into a self-contained HTML presentation — charts, stat tiles, tables, cards, columns and callouts included. No dependencies, no build chain, no JS in the output. Charts are rendered to inline SVG at build time, so the result is a single file that works offline, adapts to dark/light mode, and exports to a 16:9 PDF with one command.
Website and live demos: https://openstruct.github.io/crosspresent/
It generalises a hand-rolled presentation design system into a reusable generator, so the next deck takes minutes, not hours.
crossPresent is a single, dependency-free Python file. Install it as a
crosspresent command:
pipx install . # isolated CLI (recommended) — needs pipx
# or: uv tool install .
# or: pip install . # into the current environmentRequires Python 3.8+ and nothing else. Prefer not to install? Every command
below also works as python3 crosspresent.py … straight from the repo.
crosspresent new mydeck # scaffold a starter deck
crosspresent build mydeck.md --openThat's it.
While writing, use live preview instead of rebuilding by hand:
crosspresent serve mydeck.md # opens a browser; save = reloadWant to see everything it can do first? This builds a bundled showcase deck and opens it — no files needed, works from any directory:
crosspresent demo(From a clone of the repo you can also build the source directly:
crosspresent build examples/demo.md --open.)
Agents are good at writing Markdown, and crossPresent turns that Markdown into a finished deck — so Claude, Cursor, Copilot or any other agent can make you a presentation without hand-writing HTML.
MCP server (any MCP client). crosspresent mcp speaks the Model Context
Protocol over stdio, with four tools: crosspresent_guide (the authoring
reference), crosspresent_check (validate, errors name their slide),
crosspresent_build (Markdown text or a file → HTML) and crosspresent_pdf.
Still stdlib-only.
# Claude Code
claude mcp add crosspresent -- crosspresent mcp// Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json)
{ "mcpServers": { "crosspresent": { "command": "crosspresent", "args": ["mcp"] } } }// VS Code / GitHub Copilot (.vscode/mcp.json)
{ "servers": { "crosspresent": { "type": "stdio", "command": "crosspresent", "args": ["mcp"] } } }Not installed globally? Use "command": "python3", "args": ["/path/to/crosspresent.py", "mcp"].
Safe by default. MCP tools are driven by a model, so the server only
reads and writes inside its workspace — the folder the client starts it in,
or crosspresent mcp --root <dir>. Sources must be .md files there,
outputs must be .html/.pdf there, chart data, fonts and images must
resolve there, and it won't overwrite a file crossPresent didn't create
unless the call passes overwrite: true. Embedding only ever inlines real
image files. PDF export prints from a throwaway http://127.0.0.1 page,
never file://, so a deck can't pull other local files into the PDF.
Claude Code Agent Skill. crosspresent skill install writes
~/.claude/skills/crosspresent/SKILL.md (or --project for this repo only),
so Claude knows when to reach for crossPresent and how to write a good deck.
crosspresent skill print shows it.
Any agent with a shell. Point it at two commands:
crosspresent guide # the authoring reference, written for agents
crosspresent check deck.md --json # machine-readable errors and warnings; exit 1 on errorsFor example, add to your AGENTS.md / CLAUDE.md: "For slides or reports,
write Markdown and use crossPresent: read crosspresent guide, then
crosspresent check and crosspresent build." The website also serves the
guide as llms.txt.
Three built-in looks. Pick one in frontmatter (template: deck) or override
at build time (-t deck):
| Template | What you get | Best for |
|---|---|---|
sidebar (default) |
Sticky table of contents + full-height scrolling sections | Walkthroughs, screen-shared reviews |
deck |
Full-screen slides, snap scrolling, a slide counter and type that scales up for projectors | Actual presentations |
doc |
Single column with a TOC box at the top | Documentation, reports, READMEs-with-pictures |
Same source file works with all three — examples/demo.html,
examples/demo-deck.html and examples/demo-doc.html are the same Markdown
built three ways.
---
title: My Deck # browser title (defaults to first slide)
subtitle: Shown under the cover heading.
eyebrow: Project walkthrough # small label above the cover heading
template: sidebar # sidebar | deck | doc
palette: default # default | ocean | forest | mono | crimson
accent: "#ffb547" # theme accent (optional, overrides palette)
background: "#0f1115" # page background (optional, overrides palette)
toc_title: Contents # sidebar heading (optional)
footer: My footer text # page footer (optional)
font: system # system | serif | mono (optional)
font_file: fonts/Brand.woff2 # embed your own font (optional)
controls: true # keyboard controls + progress bar (optional)
description: One-line summary. # link-preview text (optional)
image: https://…/cover.png # link-preview image (optional)
---A palette sets the accent, the page background and the chart colors as a
matched set, for both the dark and light schemes — pick one and everything
agrees without touching a hex code (theme: works as an alias):
| Palette | Feel |
|---|---|
default |
Amber accent on near-black — the original walkthrough look |
ocean |
Cyan/blue, deep blue-black background |
forest |
Greens and earth tones |
mono |
Grayscale charts, neutral accent — print-friendly, serious |
crimson |
Warm reds/pinks |
Explicit keys win over the palette: set palette: ocean and
accent: "#ff00aa" and you get ocean's backgrounds and chart colors with
your accent.
The output follows the system color scheme: a dark theme by default and a light theme when the viewer's OS prefers light. Both are themeable, and every key is optional — leave them out and you get the built-in look.
| Key | Default | Applies to |
|---|---|---|
accent |
#ffb547 |
dark scheme accent (eyebrows, notes, first chart color) |
accent_light |
#c2530a |
light scheme accent (defaults to accent if you set one) |
background |
#0f1115 |
dark scheme page background |
background_light |
#fbfbfd |
light scheme page background |
---
title: Branded deck
accent: "#7c5cff"
background: "#14101e" # any CSS color — or a gradient:
# background: "linear-gradient(160deg, #14101e 0%, #1a1430 100%)"
---Values are dropped into CSS as-is, so any valid CSS background value works (colors, gradients). Panels, cards and charts keep their own surfaces, so an override only needs to look right behind them — very dark values pair well with the dark accent palette, very light ones with the light palette.
# Title— a title slide (gradient background; first one is the cover)## Heading— a regular slide; auto-numbered, auto-added to the TOC## Heading {#custom-id}— set the anchor yourself### Heading— a sub-heading within the current slide- The first paragraph of each slide is styled as its intro line
**bold** *italic* `code` [link](https://…) 
[[BADGE]] → neutral pill badge
[[shipped|good]] → colored badge: good, warn, bad, info, accent, purple, teal, dim```chart
{
"type": "bar",
"title": "Requests per day",
"labels": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"values": [120, 200, 150, 310, 260]
}
```| Key | Meaning |
|---|---|
type |
bar, hbar, line, area, pie, donut |
labels |
x-axis / slice labels |
values |
single series of numbers (≥ 0) |
series |
instead of values: [{"name": "a", "values": […]}, …] — gives grouped bars / multi-line + legend (bar, line, area; hbar, pie and donut are single-series) |
data |
instead of inline numbers: path to a .csv or .json file, relative to the deck (see below) |
title |
optional caption above the chart |
height |
optional SVG height (bar/line/area; default 280, minimum 80) |
colorful |
hbar only: cycle the palette per bar |
```chart
{ "type": "bar", "title": "Outcomes by week", "data": "data/weekly.csv" }
```CSV format: a header row, then one row per label — first column is the labels, every other column becomes a series (one column → a single series, several → grouped bars / multi-line with a legend):
week,passed,failed
W1,58,6
W2,60,4A .json data file is an object with labels and values (or series).
Regenerate the file in CI and rebuild — the deck stays in sync with real
output. serve watches *.csv / *.json next to the deck (and in
data/) and reloads when they change. Don't mix data with inline
labels/values/series — that's an error.
Charts become inline SVG using the theme's colors — they follow dark/light mode and print correctly. Worth knowing:
- Negative values aren't supported.
- Large numbers are abbreviated on axes and value labels:
1.2B,3.5M,150k. hbarrow labels longer than ~30 characters are truncated with an ellipsis — keep them short or use a table instead.- A bad spec (non-numeric value, unknown type, too-small height) fails the build with an error naming the slide; a label/value count mismatch builds but prints a warning.
```stats
63 | passed | green ← value | label | color (green/amber/red/blue/gray)
```
```note Optional label
A highlighted callout box.
```
> **Or as a blockquote**
> First bold line becomes the note label.
```cards
### Card one
Splits on ### into a grid. Force columns with ```cards 3
### Card two
…
```
```pills
Link text | https://example.com ← row of link chips
```
```columns 3:2
Left column — any slide Markdown, including charts
|||
Right column ← `|||` separates columns (2–4); ratio optional
```
```python
any other fence tag = code block
```
```mermaid
graph TD; A-->B
```The one exception to "no JS": if a deck contains a mermaid block, the
output includes a CDN <script> so diagrams render — that page then needs
network access. Everything else is fully offline.
A columns block puts content side by side — text next to a chart is the
classic. Separate columns with a line containing only |||; every column is
ordinary slide Markdown, so charts, lists, notes and tables all work inside.
```columns 3:2
### Why it matters
- Text and a chart on one slide
- No HTML needed
|||
```chart
{ "type": "donut", "labels": ["A", "B"], "values": [70, 30] }
```
```Two to four columns. The optional ratio (2:1, 1:1:2) needs one number
per column. On narrow screens columns stack.
The default is the system UI font. font: serif or font: mono switch to a
serif or monospace stack. To use your brand font, point font_file at a
.woff2, .woff, .ttf or .otf next to the deck — it's embedded in the
HTML as a data URI, so the file still works offline.
The deck template snaps slide by slide with the mouse wheel, trackpad,
Page Up/Down and Space. For the full presenting experience, opt in with
controls: true in frontmatter (or --controls on build/serve): arrow
keys step through slides, Home/End jump, F toggles fullscreen and a thin
progress bar runs along the top. This adds a ~1 KB inline script — the only
JavaScript crossPresent writes on request; leave it off and the output stays
script-free.
description and image become <meta name="description"> and Open Graph
tags, so a deck shared in Slack, LinkedIn or iMessage shows a proper card.
```notes
What to *say* on this slide — not what to show.
```Notes are stripped from the output entirely by default. Build (or serve)
with --notes and they render as dashed, clearly-marked boxes — so you can
keep one source file and produce both a rehearsal copy and a clean
shareable one. Add a label after the tag: ```notes Timing.
crosspresent demo build the bundled showcase deck and open it
-t, --template sidebar|deck|doc preview the demo in another template
--notes include the demo's speaker notes
--no-open build but don't open the browser
crosspresent new <name> [--force] scaffold a starter deck
crosspresent build <src.md> [<src.md> ...] build each source to <src>.html
-o, --output <path> choose output path (single source only)
-d, --output-dir <dir> write every deck's .html into <dir>
-t, --template sidebar|deck|doc override the template
--embed inline local images as data URIs
--notes include speaker notes
--controls keyboard controls + progress bar
--open open each result in a browser
crosspresent pdf <src.md> [<src.md> ...] export PDF(s) via Chrome/Edge/Chromium/Brave
-o, --output <path> choose output path (single source only)
-d, --output-dir <dir> write every PDF into <dir>
-t, --template sidebar|deck|doc deck gives 16:9 slide pages
--notes include speaker notes
--open open the PDF afterwards
crosspresent check <src.md> [--json] validate without writing; exit 1 on errors
crosspresent guide print the authoring guide (for agents too)
crosspresent skill install|print [--project] Claude Code Agent Skill
crosspresent mcp MCP server over stdio
crosspresent serve <src.md> live preview: save = auto-reload
-t, --template sidebar|deck|doc override the template
--port <n> port (default 7350)
--notes include speaker notes
--controls preview with keyboard controls
--no-open don't open the browser
build accepts several sources or a glob — crosspresent build decks/*.md
builds each next to its source, or all into one folder with --output-dir.
A deck that fails (e.g. a bad chart) is reported but doesn't stop the rest;
the command exits non-zero if any deck failed.
serve is a dev-mode preview: it builds in memory (nothing written to
disk) and injects a tiny reload script — the only time crossPresent output
contains JS you didn't ask for. build output is untouched.
| File | What it shows |
|---|---|
| examples/demo.md | Every block type, one slide each |
crosspresent pdf mydeck.md -t deck # 16:9 pages, one slide per page
crosspresent pdf report.md # sidebar/doc: regular paper pagespdf drives a Chromium-based browser you already have (Chrome, Edge,
Chromium or Brave) in headless mode — no extra dependencies. Set
CROSSPRESENT_BROWSER to point at a specific one. Local images are embedded
automatically, and mermaid decks get extra time to render.
Without a supported browser, open the HTML and use Print → Save as PDF: the print stylesheet hides the TOC and breaks one slide per page.
python3 -m unittest discover testsThe site in docs/ (GitHub Pages) is generated from the repo itself — the hero
slide, live demos and charts are real crossPresent output:
python3 site/build.py