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        # dev server with live reload
colloquium export slides.md       # PDF via a headless Chromium-based browser
colloquium capture slides.md      # per-slide PNGs for AI review

CLI Commands

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

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.

Slide Structure

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

# Welcome              ← title slide (centered, large)

---

## Key Results         ← content slide (heading + body)

### Sub-section        ← rendered as h3 inside the slide body

Normal paragraph text.

Slide Directives

Per-slide configuration via HTML comments. Place them anywhere in the slide.

## My Slide

<!-- layout: section-break -->
<!-- class: highlight special -->
<!-- style: background: #1a1a2e -->
<!-- notes: Remember to mention X -->
<!-- align: center -->
<!-- valign: bottom -->
<!-- columns: 2 -->
<!-- rows: 35/65 -->
<!-- padding: compact -->
<!-- size: large -->
<!-- title: hidden -->

Layouts

Columns

Split content with ||| between columns:

<!-- columns: 2 -->
## Results

Left column content

|||

Right column content

Arbitrary numeric ratios are allowed, e.g. 25/75, 33/67, or 1/2/1.

Rows

Split a slide vertically with === between row blocks:

<!-- rows: 35/65 -->
## Overview

Top row content

===

Bottom row content

Arbitrary numeric ratios are allowed here too, e.g. 25/75 or 20/30/50.

To use columns inside a specific row block, add a row-local directive at the top of that row:

<!-- rows: 35/65 -->
## Overview

<!-- row-columns: 40/60 -->
Left text

|||

Right text

===

![Wide image](figure.png)

At the slide root, use either columns: or rows:. For nested layouts, use row-columns: inside a row block.

Text & Spacing

Other

See the examples on the website for rendered decks and copy-paste patterns, or browse the source in examples/.

Bibliography

Frontmatter options:

bibliography: refs.bib
citation_style: author-year
citation_order: auto

• citation_style: numeric keeps citations and references in first-appearance order.
• Non-numeric styles default to alphabetical ordering.
• Set citation_order: appearance to keep author-year or title-year citations in source order.

To add appendix or backup slides after the automatically generated references, place them at the end of the markdown and add a slide directive:

---

<!-- after: references -->

## Backup analysis

Extra material

These post-reference slides render after the references section, but they do not contribute to the footer {N} total. If the main talk plus generated references totals 30 slides, the first post-reference slide is numbered 31/30.

Content Features

Math (KaTeX) — inline $E=mc^2$ and display $$\sum_{i=1}^n x_i$$

Code (highlight.js) — fenced code blocks with language syntax highlighting

Tables — standard markdown tables

Images — ![alt](url) with automatic sizing (SVG supported for vector graphics)

To enable numbered figure captions across a whole deck, add this to frontmatter:

figure_captions: true

Standalone markdown images will render as numbered figures, using the alt text as the caption:

![Training recipe overview](assets/recipe.png)

This renders as Figure 1: Training recipe overview. Leave the alt text empty to suppress the caption:

![](assets/recipe.png)

If you only want captions on selected slides, use figure-captions as a slide class instead:

<!-- class: figure-captions -->

![Training recipe overview](assets/recipe.png)

If the deck enables figure_captions: true, add no-figure-captions to a slide to opt that slide out.

Text Sizes

Control font size on any element or block using HTML class attributes:

<span class="text-2xl">Big emphasis text</span>

Normal paragraph text.

<div class="text-sm">

- Dense bullet point one
- Dense bullet point two

</div>

<span class="text-xs">Footnote or citation</span>

<div class="colloquium-spacer-md"></div>

<div class="colloquium-footnote">
This is useful for speaker-side caveats or details that should stay visually secondary.
</div>

Spacing and Footnotes

Use small spacer blocks when you want more breathing room between prose and an example:

After pretraining we are left with a glorified autocomplete model.

<div class="colloquium-spacer-md"></div>

```conversation
messages:
  ...

Available spacer helpers:

- `colloquium-spacer-sm`
- `colloquium-spacer-md`
- `colloquium-spacer-lg`

Use `colloquium-footnote` for secondary caveats or context inside the slide body:

```markdown
<div class="colloquium-footnote">
Base models are also becoming more flexible through midtraining and related data mixtures.
</div>

For slide-level footnotes that sit above the footer, use directives:

<!-- footnote: Base models are also becoming more flexible through midtraining. -->
<!-- footnote-right: Right-aligned note for this slide. -->

These share the same bottom-left / bottom-right area as floating citations, with citations stacked above the footnote when both are present.

For inline numbered footnotes, use ^[...] where you want the marker to appear:

This sentence ends with a numbered footnote.^[Base models are also becoming more flexible through midtraining.]

Inline footnotes collect into the same floating footer area and are numbered per slide. They default to the right side; set the side explicitly when needed:

<!-- footnotes: left -->

Use the dedicated example deck in examples/footnotes/ for copy-paste patterns.

Charts

Inline charts via Chart.js using YAML in fenced code blocks:

```chart
type: line
height: 500
width: 800
data:
  labels: [Q1, Q2, Q3, Q4]
  datasets:
    - label: Revenue
      data: [10, 25, 40, 60]
      color: "#4AA691"
options:
  scales:
    y:
      ticks:
        prefix: "$"
        suffix: "K"
```

Conversations

Render LLM-style chat bubbles using YAML in fenced code blocks:

```conversation
size: 0.9
messages:
  - role: user
    content: "What is RLHF?"
  - role: assistant
    model: "Tülu 3 405B"
    content: "**RLHF** is a technique for aligning language models..."
  - role: system
    content: "You are a helpful AI assistant."
```

Message content supports markdown formatting (bold, italic, inline code).

Optional conversation settings:

Boxes

Render a rounded callout card using YAML in fenced code blocks:

```box
title: DPO became popular because:
tone: accent
content: |
  - Far simpler to implement
  - Far cheaper to run
  - Often reaches most of the final performance
```

Optional box settings:

box supports a title-only callout too:

```box
title: Core idea
tone: accent
```

The supported tones are:

Built With Badge

Render a compact GitHub badge anywhere in a slide using the normal layout tools:

<!-- align: right -->
<!-- valign: bottom -->

```builtwith
repo: natolambert/colloquium
```

Optional settings:

Because it is a normal block element, you can place it with columns, rows, alignment utilities, or raw HTML wrappers instead of relying on footer-specific behavior.

Citations

Add a .bib file to your project and reference it in frontmatter:

---
bibliography: refs.bib
citation_style: author-year   # or "numeric" or "title-year"
---

Use [@key] to cite in slides:

The foundational work on RLHF [@christiano2017] introduced reward models.

Multiple citations: [@christiano2017; @ouyang2022]

A References slide is automatically appended with only the cited works.

Keyboard Shortcuts

Click the slide counter to open the slide picker. Click left 1/3 of screen to go back, right 2/3 to go forward.

PPTX Export (Experimental)

Export to PowerPoint/Google Slides format:

uv pip install colloquium[pptx]     # install optional dependency
colloquium export --pptx slides.md  # → slides.pptx

This produces a reasonable starting point, but some colloquium features lose fidelity: citations are flattened, math renders as raw LaTeX, and custom themes/CSS aren't applied. Charts and tables become native editable PPTX objects.

PDF Export

Two options:

1. Browser: Open the HTML file and Cmd+P / Ctrl+P — print CSS makes all slides visible with page breaks, footers with slide numbers included
2. CLI: colloquium export slides.md uses a headless Chromium-based browser

Slide Capture

Capture individual slides as 1280x720 PNG images — useful for AI agents to visually review slides, or for thumbnails and previews.

colloquium capture slides.md              # all slides → slides/ directory
colloquium capture slides.md -o ./imgs/   # custom output directory
colloquium capture slides.md --slide 3    # capture only slide 3

This exports to PDF first (one headless Chrome launch), then splits pages into PNGs with Ghostscript. Requires Chrome and gs:

brew install ghostscript   # macOS
apt install ghostscript    # Linux

Output

Everything builds to a single self-contained HTML file. CSS and JS are inlined; math (KaTeX) and code highlighting (highlight.js) load from CDN.

Contributing Elements

Custom block-level elements live in colloquium/elements/. Each module exposes:

• PATTERN — compiled regex matching <pre><code class="language-X">...</code></pre>
• process(yaml_str) -> str — converts the YAML content to HTML
• reset() (optional) — resets any counters between builds

The registry in colloquium/elements/__init__.py auto-wires them into the build pipeline. To add a new element:

1. Create colloquium/elements/my_element.py with PATTERN, process, and optionally reset
2. Import and register it in colloquium/elements/__init__.py
3. Add any element-specific CSS to colloquium/themes/default/theme.css