Skip to content
/ cdl-slides Public

Python package, scripts, resources, themes, and convenience functions for constructing CDL-themed slide presentations

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

ContextLab/cdl-slides

BranchesTags

Repository files navigation

CDL Slides

Compile Markdown files into beautiful CDL-themed Marp presentations. Includes the full Contextual Dynamics Lab slide theme with bundled fonts, images, and CSS.

Theme gallery

Title Slide Callout Boxes Tip & Warning
Title Callouts Tip & Warning
Definition, Example & Important Code Highlighting Math (KaTeX)
Def/Ex/Imp Code Math
Manim Animations Flow Diagrams Emoji Figures
Manim Flow Emoji
Two-Column Layout Simple Table Output Formats
Two-Column Table Formats

Table of contents

Features

  • Cross-platform: Works on macOS, Windows, and Linux
  • Zero-config Marp CLI: Automatically downloads the Marp CLI standalone binary on first use — no Node.js required
  • Multiple output formats: HTML, PDF, and PPTX
  • Bundled theme: Complete CDL/Dartmouth-branded theme with custom fonts, colors, and layouts
  • Smart preprocessing: Auto-splits long code blocks and tables across slides
  • Flow diagrams: Simple ```flow syntax for pipeline diagrams
  • Manim animations: Embed animated equations and visualizations with ```manim blocks (optional)
  • Auto-scaling: Automatically adjusts font size for dense slides
  • Syntax highlighting: Code blocks with line numbers via Pygments
  • Math support: KaTeX for inline and display equations
  • Callout boxes: Note, tip, warning, definition, example, and important boxes

Installation

macOS:

brew install pango cairo ffmpeg
pip install cdl-slides

Linux (Debian/Ubuntu):

sudo apt-get install -y libpango1.0-dev libcairo2-dev ffmpeg
pip install cdl-slides

Windows:

pip install cdl-slides

Then run setup to download Marp CLI:

cdl-slides setup

Or install from source:

git clone https://github.com/ContextLab/cdl-slides.git
cd cdl-slides
pip install -e .

Marp CLI resolution

cdl-slides finds or installs Marp CLI automatically in this order:

  1. System PATH — uses your existing marp install (npm, brew, etc.)
  2. Cached binary — standalone binary downloaded on first use (~~/Library/Caches/cdl-slides/ on macOS, ~/.cache/cdl-slides/ on Linux, AppData\Local\cdl-slides\ on Windows)
  3. npx fallback — runs @marp-team/marp-cli via npx if Node.js is available

To check your Marp CLI status:

cdl-slides version

Quick start

  1. Create a Markdown file with CDL theme front matter:
---
marp: true
theme: cdl-theme
math: katex
transition: fade 0.25s
author: Contextual Dynamics Lab
---

# My Presentation Title
### Subtitle

Your Name
Your Institution

---

# Slide Two

- Point one
- Point two
- Point three
  1. Compile to HTML and PDF:
cdl-slides compile my_presentation.md
  1. Output files are created alongside the input:
    • my_presentation.html
    • my_presentation.pdf

CLI reference

cdl-slides compile

Compile a Markdown file into a presentation.

Usage: cdl-slides compile [OPTIONS] INPUT_FILE

Options:
  -o, --output PATH      Output file or directory (default: same dir as input)
  -f, --format TEXT       Output format: html, pdf, pptx, both (default: both)
  -l, --lines INTEGER     Max code lines per slide before splitting (default: 30)
  -r, --rows INTEGER      Max table rows per slide before splitting (default: 10)
  --no-split              Disable auto-splitting of code blocks and tables
  --keep-temp             Keep temporary processed files for debugging
  -t, --theme-dir PATH    Custom theme directory (overrides bundled CDL theme)
  --no-animations         Skip processing of animate blocks (useful for CI)
  --help                  Show this message and exit.

Examples:

# Compile to HTML only
cdl-slides compile slides.md --format html

# Compile to PDF only
cdl-slides compile slides.md --format pdf

# Compile to PowerPoint
cdl-slides compile slides.md --format pptx

# Compile with custom output location
cdl-slides compile slides.md --output ./build/

# Compile with custom code splitting threshold
cdl-slides compile slides.md --lines 15 --rows 5

cdl-slides init

Create a new presentation from a template.

cdl-slides init                    # Create template in current directory
cdl-slides init ./my-presentation  # Create template in specific directory

cdl-slides version

Show version and Marp CLI status.

cdl-slides version

cdl-slides setup

Pre-download the Marp CLI standalone binary. This is optional — Marp CLI is automatically downloaded on first compile if not already installed.

cdl-slides setup

Slide authoring guide

Front Matter

Every CDL presentation starts with this YAML front matter:

---
marp: true
theme: cdl-theme
math: katex
transition: fade 0.25s
author: Contextual Dynamics Lab
---

Callout Boxes

The CDL theme includes six styled box types:

<div class="note-box" data-title="Title">
Content here with **Markdown** support.
</div>

<div class="tip-box" data-title="Pro Tip">
Helpful advice goes here.
</div>

<div class="warning-box" data-title="Caution">
Important warnings here.
</div>

<div class="definition-box" data-title="Term">
Definition of the term.
</div>

<div class="example-box" data-title="Example">
A worked example.
</div>

<div class="important-box" data-title="Key Point">
Critical information.
</div>

Two-Column Layouts

For two-column content, wrap each column's content in a callout box for best results:

<div style="display: flex; gap: 1.5em;">
<div style="flex: 1;">

<div class="example-box" data-title="Left topic">

- First point
- Second point

</div>

</div>
<div style="flex: 1;">

<div class="example-box" data-title="Right topic">

- First point
- Second point

</div>

</div>
</div>

Any box type works (tip-box, warning-box, note-box, etc.). The boxes give columns clear visual boundaries and headers.

Flow Diagrams

Use the ```flow syntax for simple pipeline diagrams:

```flow
[Input:blue] --> [Process:green] --> [Output:orange]
```
<!-- caption: A data processing pipeline -->

Available colors:

Color Alias Description
green — Dartmouth Green (primary brand)
blue river-blue River Blue
navy river-navy River Navy
teal — Blue-green
spring spring-green Spring Green
rich-spring — Rich Spring Green
yellow summer Summer Yellow
orange bonfire Bonfire Orange
tuck tuck-orange Tuck Orange
red bonfire-red Bonfire Red
violet purple Violet
brown autumn Autumn Brown
gray granite, web-gray Granite Gray

Manim Animations

Embed animated math visualizations using the Animate DSL — a simple, declarative syntax that compiles to Manim Community. Animations are rendered to transparent GIFs and embedded in slides.

FFmpeg is bundled automatically via imageio-ffmpeg — no system ffmpeg installation required.

Usage:

```animate
height: 400
write equation "E = mc^2" as eq at center
wait 0.5
fade-in eq
```

The preprocessor automatically renders to GIF and embeds in your slide. Rendered GIFs are cached by content hash, so unchanged animations won't re-render.

Animate DSL (Simplified Animation Syntax)

The animate DSL provides a simpler alternative to writing raw manim Python code. It uses a declarative syntax that gets transpiled to manim automatically.

Basic equation example:

```animate
height: 400
write equation "E = mc^2" as eq1 at center
wait 0.5
fade-in eq1
```

Graph/plot example:

```animate
height: 400
create axes x=[0,6.28,1.57] y=[-1.5,1.5,0.5] as ax
plot "np.sin(x)" on ax color=blue as wave
```

Metadata options:

Option Default Description
height 500 Image height in pixels
width 960 Image width in pixels
quality high Render quality (low/medium/high)
scale 1.0 Scale factor for equations and text (e.g., 2.5 for larger)

Object commands:

Command Description Example
write equation "LaTeX" as NAME Create LaTeX equation write equation "E = mc^2" as eq1
write text "string" as NAME Create text object write text "Hello" as title
create circle color=COLOR as NAME Create colored circle create circle color=blue as c1
create square color=COLOR as NAME Create colored square create square color=red as s1
create arrow color=COLOR as NAME Create colored arrow create arrow color=green as a1
create axes x=[min,max,step] y=[min,max,step] as NAME Create coordinate axes create axes x=[-3,3,1] y=[-1,1,0.5] as ax
create graph "formula" x=[min,max] color=COLOR as NAME Create standalone function graph create graph "x**2" x=[-2,2] color=red as parabola

Plot commands:

Command Description Example
plot "formula" on AXES color=COLOR as NAME Plot function on existing axes plot "np.sin(x)" on ax color=blue as wave

Animation commands:

Command Description
fade-in NAME Fade in an object
fade-out NAME Fade out an object
draw NAME Draw/create an object (for axes, graphs)
transform NAME1 -> NAME2 Transform one object into another
wait SECONDS Wait for specified duration

Generic manim escape (for advanced use):

Command Description Example
manim <python_code> as NAME Execute any manim code manim Dot().move_to(ax.c2p(1,1)) as dot

Position modifiers:

Modifier Description
at center Place at screen center
above NAME Place above another object
below NAME Place below another object
left-of NAME Place to the left of another object
right-of NAME Place to the right of another object

Available colors: blue, red, green, yellow, orange, white, black

Animation support is included by default with pip install cdl-slides.

Scale Directives

For dense slides, use scale directives to adjust font size:

<!-- _class: scale-80 -->
# Dense Slide Title

Lots of content here...

Available scales: scale-50 through scale-95 in increments of 5.

Note: The preprocessor auto-injects scale classes when slides overflow, so manual scaling is rarely needed.

Emoji Figures

<div class="emoji-figure">
  <div class="emoji-col">
    <span class="emoji emoji-xl emoji-bg emoji-bg-navy">📊</span>
    <span class="label">Data</span>
  </div>
  <div class="emoji-col">
    <span class="emoji emoji-xl emoji-bg emoji-bg-green">🔬</span>
    <span class="label">Analysis</span>
  </div>
</div>

Available backgrounds: emoji-bg-navy, emoji-bg-green, emoji-bg-blue, emoji-bg-orange, emoji-bg-purple, emoji-bg-teal.

Math (KaTeX)

Inline: $E = mc^2$

Display:

$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

Code Blocks

Code blocks are automatically:

  • Syntax highlighted (via Pygments)
  • Line numbered
  • Split across slides if they exceed --lines threshold (default: 30)

Tables

Markdown tables are automatically split across slides if they exceed --rows threshold (default: 10 data rows).

Arrow Syntax

Use arrow shorthand in slides:

A --[80]-> B --[lg]-> C

Options: --[80]-> (pixel width), --[lg]-> (named size: sm, md, lg, xl).

Bundled Fonts

The package includes these fonts for consistent rendering across platforms:

  • Avenir LT Std (Light, Book, Roman, Medium, Heavy, Black) — body text
  • Fira Code (Regular, Medium, Bold) — code blocks
  • Noto Sans SC (Variable) — CJK character support

Development

# Clone and install in development mode
git clone https://github.com/ContextLab/cdl-slides.git
cd cdl-slides
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linter
ruff check src/ tests/
ruff format src/ tests/

License

MIT License. See LICENSE for details.

Links

About

Python package, scripts, resources, themes, and convenience functions for constructing CDL-themed slide presentations

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Feb 7, 2026

Packages

No packages published

Languages