Colloquium

Markdown-based slide creation tool for research talks. Git-friendly, AI-drivable, single-file HTML output.

Docs · Core Example (RLHF Book) · PyPI

Install

Colloquium uses uv for fast, reliable Python package management.

uv tool install colloquium
# or inside a project
uv pip install colloquium

For development:

git clone https://github.com/natolambert/colloquium.git
cd colloquium
uv pip install -e ".[dev]"

Quick Start

Create a markdown file:

---
title: "My Talk"
author: "Jane Doe"
date: "2026-02-22"
---

# My Talk

Jane Doe

---

## Key Results

- Finding one
- Finding two

---

## Conclusion

Thanks for listening!

Build it:

colloquium build slides.md        # → slides.html
colloquium serve slides.md        # rebuilds and reloads the browser tab on save
colloquium export slides.md       # PDF via a headless Chromium-based browser
colloquium capture slides.md      # per-slide PNGs for AI review
colloquium share-image slides.md  # first slide as the link-preview card (see below)

Add url and share_image: auto to the frontmatter and the built deck links to that capture, so the URL unfurls like this in Slack, X, or iMessage:

Details in Share images.

CLI Commands

Command	Description
colloquium build <file.md>	Build to self-contained HTML
colloquium serve <file.md>	Dev server: rebuilds on save and reloads the open browser tab on the same slide (--no-reload to only rebuild)
colloquium export <file.md>	PDF export (requires a Chromium-based browser)
colloquium capture <file.md>	Capture slides as individual PNGs
colloquium share-image <file.md>	Capture the first slide as the deck's share (Open Graph) image, <deck>-share.png

Frontmatter Reference

All configuration goes in the YAML frontmatter block at the top of the file.

---
title: "Talk Title"
author: "Author Name"
date: "2026-02-22"
theme: default
aspect_ratio: "16:9"

fonts:
  heading: "Playfair Display"    # Google Font for h1/h2/h3
  body: "Source Sans 3"          # Google Font for body text

footer:
  left: "https://example.com/logo.png"   # image URL → logo, plain text → text
  center: "My Talk Title"
  right: "auto"                           # "auto" → slide numbers "3 / 12"

custom_css: ".slide h2 { color: red; }"   # inline CSS overrides, or a .css file: custom_css: deck.css
---

Key	Default	Description
title	"Untitled"	Presentation title (used in <title> and title slides)
author	""	Author name
date	""	Date string
theme	"default"	Theme name
aspect_ratio	"16:9"	Slide aspect ratio
fonts.heading	Inter	Google Font for headings
fonts.body	Inter	Google Font for body text
footer.left	""	Left footer zone (text, image URL, or "auto"), or a list of them shown side by side
footer.center	""	Center footer zone
footer.right	"auto"	Right footer zone ("auto" = slide numbers)
custom_css	""	Additional CSS injected into the page: inline CSS, or the path of a .css file next to the deck (see Custom CSS from a file)
url	""	Canonical URL of the published deck; adds og:url and a canonical link, and resolves a relative share_image
share_image	false	Share (Open Graph) image: auto for <deck>-share.png next to the HTML (see Share images), or a path or URL
pptx	—	PPTX template export settings; see PPTX Export

Footer text supports {n} (slide number) and {N} (total slides) for custom counters, e.g. "Lambert {n}/{N}" → "Lambert 6/23".

When footer: is omitted entirely, a minimal footer with just the slide counter in the right zone is used.

Use {n} and {N} placeholders to embed the current slide number and total count inline with text:

footer:
  left: "rlhfbook.com"
  right: "Lambert {n}/{N}"    # renders as "Lambert 3/25"

If no zone uses "auto", {n}, or {N}, the slide counter is automatically placed in the first empty zone.

Custom CSS from a file

When a deck's styling grows past a few rules, point custom_css at a stylesheet instead of holding the CSS in the frontmatter:

custom_css: lecture.css    # a path ending in .css, relative to the markdown file

The file's contents are inlined into the built HTML at build time, so the output is still a single self-contained file and PDF export, share images, and hosting work unchanged. colloquium serve watches the stylesheet as well as the markdown, so saving either rebuilds and reloads the deck. A missing file is a build error that names the path. See examples/custom-css for a deck styled this way:

Slide Structure

Slides are separated by --- on its own line. The first heading in each slide becomes the slide title:

This is the beginning of the README. Read the rest at the original. Read the full README ↗