Skip to content

Latest commit

 

History

8 Commits

Folders and files

Repository files navigation

crossPresent

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.

Install

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 environment

Requires Python 3.8+ and nothing else. Prefer not to install? Every command below also works as python3 crosspresent.py … straight from the repo.

Quickstart

crosspresent new mydeck          # scaffold a starter deck
crosspresent build mydeck.md --open

That's it.

While writing, use live preview instead of rebuilding by hand:

crosspresent serve mydeck.md     # opens a browser; save = reload

Want 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.)

Use with AI agents

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 errors

For 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.

Templates

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.

Authoring guide

Frontmatter

---
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)
---

Palettes

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.

Theming — accent and background

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.

Slides

  • # 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

Inline markup

**bold**  *italic*  `code`  [link](https://…)  ![alt](image.png)
[[BADGE]]            → neutral pill badge
[[shipped|good]]     → colored badge: good, warn, bad, info, accent, purple, teal, dim

Charts — fenced block tagged chart, JSON inside

```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

Charts from data files

```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,4

A .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.
  • hbar row 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.

Other blocks

```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.

Columns

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.

Fonts

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.

Presenter controls

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.

Link previews

description and image become <meta name="description"> and Open Graph tags, so a deck shared in Slack, LinkedIn or iMessage shows a proper card.

Speaker notes

```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.

CLI

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.

Examples

File What it shows
examples/demo.md Every block type, one slide each

Exporting to PDF

crosspresent pdf mydeck.md -t deck      # 16:9 pages, one slide per page
crosspresent pdf report.md              # sidebar/doc: regular paper pages

pdf 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.

Tests

python3 -m unittest discover tests

Website

The 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

Releases

Packages

Contributors

Languages