presenterm - Terminal Slideshow Tool

presenterm is a modern terminal-based presentation tool that renders markdown files as slides. It supports themes, code syntax highlighting, images, diagram rendering (mermaid, d2), mathematical formulas (LaTeX, typst), and can export to PDF or HTML.

Core Principles

• Markdown-first: Write presentations in familiar markdown syntax

• Terminal-native: Runs entirely in the terminal with rich rendering

• Advanced rendering: Render mermaid/d2 diagrams and LaTeX/typst formulas as images

• Presentation mode: Separate presentation view with speaker notes support

• Export capabilities: Generate PDF or HTML from markdown slides

• Code execution: Execute code snippets during presentations

• Theme support: Multiple built-in themes and custom theme support

Installation

macOS (Homebrew)

brew install presenterm

Cargo

cargo install presenterm

From source

git clone https://github.com/mfontanini/presenterm cd presenterm cargo install --path .

Basic Usage

Running Presentations

Run a presentation

presenterm presentation.md

Use presentation mode (full-screen, controls hidden)

presenterm -p presentation.md presenterm --present presentation.md

Use specific theme

presenterm -t dark presentation.md presenterm --theme catppuccin presentation.md

List available themes

presenterm --list-themes

Show current theme

presenterm --current-theme

Exporting

Export to PDF

presenterm -e presentation.md presenterm --export-pdf presentation.md

Export to PDF with specific output path

presenterm -e presentation.md -o output.pdf presenterm --export-pdf presentation.md --output slides.pdf

Export to HTML

presenterm -E presentation.md presenterm --export-html presentation.md -o presentation.html

Specify temporary path for export

presenterm -e presentation.md --export-temporary-path /tmp/presenterm

Markdown Syntax

Slide Separators

<!-- Slides are separated by --- -->

First Slide

Content here

Second Slide

More content

Third Slide

Final slide

Slide Layout

Title Slide

Subtitle

Author Name

Content Slide

• Bullet point 1
• Bullet point 2
  • Nested point
• Bullet point 3

Code Slide

fn main() {
    println!("Hello, presenterm!");
}
``` (triple backtick)

---

# Quote Slide

> "The best way to predict the future is to invent it."
> — Alan Kay

Speaker Notes

# My Slide

Visible content

<!-- presenter notes
These notes are only visible in presentation mode
They won't appear on the slide itself
-->

More visible content

---

# Another Slide

<!-- speaker notes
- Remember to mention X
- Don't forget Y
- Emphasize Z
-->

Images

# Image Slide

![Description](path/to/image.png)

---

# Centered Image

![](./logo.png)

Tables

# Table Example

| Feature | Status | Priority |
|---------|--------|----------|
| Export  | Done   | High     |
| Themes  | Done   | High     |
| Images  | Done   | Medium   |

Code Highlighting

# Syntax Highlighting

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

fn factorial(n: u64) -> u64 {
    (1..=n).product()
}

const greet = (name) => {
    console.log(`Hello, ${name}!`);
};

Code Execution

Executable Code Blocks

Enable code snippet execution

presenterm -x presentation.md presenterm --enable-snippet-execution presentation.md

Enable auto-execution with replacement

presenterm -X presentation.md presenterm --enable-snippet-execution-replace presentation.md

Validate snippets without running

presenterm --validate-snippets presentation.md

Executable Code Syntax

Live Demo

echo "This will execute when you advance to this slide"
date

Auto-Replace Demo

ls -la

<!-- The output will replace the code block -->

Advanced Rendering

presenterm supports rendering diagrams and formulas directly from code blocks, converting them to images during presentation load.

Mermaid Diagrams

Render mermaid diagrams using the +render attribute.

Requirements:

• Install mermaid-cli: npm install -g @mermaid-js/mermaid-cli

Syntax:

sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I'm good thanks!
    Alice-)Bob: See you later!

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

pie title Project Time Distribution
    "Development" : 40
    "Testing" : 25
    "Documentation" : 20
    "Meetings" : 15

Configuration (in config.yaml):

mermaid:

Theme selection

theme: dark

Background color

background: "#2E3440"

Image scaling

scale: 2.0

Size control with width attribute:

graph LR
    A --> B --> C

Performance Note:

• Rendering takes ~2 seconds per diagram

• Rendered asynchronously (default 2 threads)

d2 Diagrams

Render d2 diagrams for architecture and system diagrams.

Requirements:

• Install d2: brew install d2 or download from releases

Syntax:

# System Architecture
web_server: Web Server {
  shape: rectangle
}
database: Database {
  shape: cylinder
}
cache: Redis Cache {
  shape: stored_data
}

web_server -> database: queries
web_server -> cache: reads/writes

my_table: {
  shape: sql_table
  id: int {constraint: primary_key}
  username: varchar(255)
  email: varchar(255)
  created_at: timestamp
}

direction: right

users -> api: HTTP requests
api -> auth: validate token
api -> database: query data
api -> cache: check cache

Configuration (in config.yaml):

d2:

Theme selection

theme: "Nord"

Image scaling

scale: 1.5

Size control:

A -> B -> C

LaTeX Formulas

Render LaTeX mathematical formulas as images.

Requirements:

• Install typst: brew install typst or cargo install typst-cli

• Install pandoc: brew install pandoc

How it works:

• Pandoc converts LaTeX to typst

• Typst renders the formula to an image

Syntax:

\[ \sum_{n=1}^{\infty} 2^{-n} = 1 \]

\[
E = mc^2
\]

\[
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
\]

\[
\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right) = f(x)
\]

\[
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
\]

Configuration (in config.yaml):

Pixels per inch for formula rendering

typst: ppi: 300

Size control:

\[ \oint_C \mathbf{F} \cdot d\mathbf{r} = \iint_S (\nabla \times \mathbf{F}) \cdot d\mathbf{S} \]

Typst Formulas

Render typst formulas directly (bypassing LaTeX conversion).

Requirements:

• Install typst: brew install typst

Syntax:

$ sum_(n=1)^oo 1/n^2 = pi^2/6 $

$ integral_(-oo)^oo e^(-x^2) d x = sqrt(pi) $

$ mat(
  1, 2;
  3, 4;
) $

Benefits over LaTeX:

• Faster (no pandoc conversion step)

• Native typst syntax

• More modern formula typesetting

Rendering Configuration

Global config.yaml settings:

Formula rendering

typst: ppi: 300 # Pixels per inch for formulas

Mermaid diagrams

mermaid: theme: dark background: "#2E3440" scale: 2.0

d2 diagrams

d2: theme: "Nord" scale: 1.5

Complete Rendering Example

System Architecture

users: Users {
  shape: person
}
lb: Load Balancer {
  shape: rectangle
}
api: API Servers {
  shape: rectangle
}
db: Database {
  shape: cylinder
}

users -> lb
lb -> api: distribute
api -> db: query

Request Flow

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    participant C as Cache

    U->>A: Request data
    A->>C: Check cache
    alt Cache hit
        C-->>A: Return cached data
    else Cache miss
        A->>D: Query database
        D-->>A: Return data
        A->>C: Update cache
    end
    A-->>U: Response

Algorithm Complexity

\[
T(n) = \begin{cases}
O(1) & \text{best case} \\
O(\log n) & \text{average case} \\
O(n) & \text{worst case}
\end{cases}
\]

Mathematical Formula

$ P(A|B) = (P(B|A) dot P(A)) / P(B) $

Image Protocols

Auto-detect best protocol

presenterm --image-protocol auto presentation.md

Use iTerm2 protocol

presenterm --image-protocol iterm2 presentation.md

Use kitty protocol (local mode)

presenterm --image-protocol kitty-local presentation.md

Use kitty protocol (remote mode)

presenterm --image-protocol kitty-remote presentation.md

Use sixel protocol

presenterm --image-protocol sixel presentation.md

Use ASCII blocks (fallback)

presenterm --image-protocol ascii-blocks presentation.md

Themes

Built-in Themes

List all available themes

presenterm --list-themes

Common themes:

presenterm -t dark presentation.md presenterm -t light presentation.md presenterm -t catppuccin presentation.md presenterm -t dracula presentation.md presenterm -t gruvbox presentation.md presenterm -t monokai presentation.md presenterm -t nord presentation.md presenterm -t solarized-dark presentation.md presenterm -t solarized-light presentation.md

Custom Themes

Use custom theme from config

presenterm -c ~/.config/presenterm/config.yaml presentation.md presenterm --config-file custom-config.yaml presentation.md

Speaker Notes Mode

Publishing Speaker Notes

Publish speaker notes to local network

presenterm -P presentation.md presenterm --publish-speaker-notes presentation.md

Listen for speaker notes (presenter's view)

presenterm -l presenterm --listen-speaker-notes

This allows you to:

• Run presentation on one screen

• View speaker notes on another device/screen

• Perfect for dual-monitor setups

Validation

Validate that slides don't overflow terminal

presenterm --validate-overflows presentation.md

Validate code snippets

presenterm --validate-snippets presentation.md

Combine validations

presenterm --validate-overflows --validate-snippets presentation.md

Keyboard Controls

During Presentation

Navigation: ←/→ Previous/Next slide Space/Enter Next slide Backspace Previous slide Home First slide End Last slide g Go to specific slide (enter number)

Display: f Toggle fullscreen q/Esc Quit presentation

Code Execution: e Execute code block (with -x flag)

Help: ? Show help/controls

Configuration

Config File Location

Default config locations:

- Linux: ~/.config/presenterm/config.yaml

- macOS: ~/Library/Application Support/presenterm/config.yaml

- Windows: %APPDATA%\presenterm\config.yaml

Specify custom config

presenterm -c /path/to/config.yaml presentation.md

Example Configuration

config.yaml

theme: catppuccin image_protocol: auto

Default options

presentation_mode: true validate_overflows: true

Code execution

enable_snippet_execution: false

Common Workflows

Workflow 1: Create Simple Presentation

1. Create markdown file

cat > demo.md << 'EOF'

Welcome

A presenterm demo

Key Features

• Terminal-based
• Markdown syntax
• Multiple themes
• Export to PDF/HTML

Thank You!

Questions? EOF

2. Run presentation

presenterm -p demo.md

3. Export to PDF

presenterm -e demo.md -o demo.pdf

Workflow 2: Technical Presentation with Code

1. Create presentation with code examples

cat > tech-talk.md << 'EOF'

Technical Deep Dive

Rust Async Programming

Basic Example

async fn fetch_data() -> Result<String, Error> {
    let response = reqwest::get("https://api.example.com")
        .await?;
    response.text().await
}

<!-- presenter notes Explain async/await syntax Mention error handling -->

Live Demo

cargo --version
rustc --version

Questions?

EOF

2. Present with code execution enabled

presenterm -x -p tech-talk.md

3. Validate before sharing

presenterm --validate-overflows --validate-snippets tech-talk.md

4. Export for distribution

presenterm -e tech-talk.md -o tech-talk.pdf

Workflow 3: Dual-Screen Presentation

Terminal 1 (presenter view with notes)

presenterm -P presentation.md

Terminal 2 (or another device - audience view)

presenterm -l

This shows:

- Terminal 1: Full presentation with speaker notes visible

- Terminal 2: Synchronized view following presenter

Workflow 4: Themed Corporate Presentation

1. Create config with company theme

mkdir -p ~/.config/presenterm cat > ~/.config/presenterm/config.yaml << 'EOF' theme: solarized-light presentation_mode: true validate_overflows: true EOF

2. Create presentation

vim quarterly-review.md

3. Preview with theme

presenterm quarterly-review.md

4. Export with theme applied

presenterm -e quarterly-review.md -o quarterly-review.pdf

5. Also export HTML version

presenterm -E quarterly-review.md -o quarterly-review.html

Workflow 5: Conference Talk

Conference Talk Template

About Me

• Name
• Title
• Company
• Twitter: @handle

<!-- presenter notes

• Smile at audience
• Check time: should be at 2 minutes -->

Agenda

1. Problem Statement
2. Our Approach
3. Demo
4. Results
5. Q&A

Problem Statement

The Challenge

• Point 1
• Point 2
• Point 3

<!-- presenter notes

• Share personal experience
• Ask if anyone relates -->

Live Demo

./demo.sh

Results

Thank You!

Questions?

Slides: https://example.com/slides Code: https://github.com/user/repo

Best Practices

Slide Design

• One idea per slide: Keep slides focused

• Minimal text: Use bullets, not paragraphs

• Visual hierarchy: Use headings effectively

• Code readability: Keep code snippets short and readable

• Consistent formatting: Use same style throughout

File Organization

presentation/ ├── slides.md # Main presentation ├── images/ # Image assets │ ├── logo.png │ ├── diagram1.png │ └── screenshot.png ├── code/ # Code examples │ ├── example1.rs │ └── demo.py └── export/ # Exported versions ├── slides.pdf └── slides.html

Speaker Notes

Slide Title

Visible content

<!-- presenter notes Time checkpoint: 5 minutes Key talking points:

• Emphasize security aspect
• Mention customer feedback
• Transition to demo Reminder: drink water! -->

Code Examples

• Syntax highlighting: Always specify language

• Keep it short: 10-15 lines max per slide

• Highlight key parts: Use comments to draw attention

• Test code: Ensure examples are correct

• Use exec sparingly: Only for impactful demos

Validation Before Presenting

Full validation checklist

presenterm --validate-overflows presentation.md presenterm --validate-snippets presentation.md presenterm -p presentation.md # Dry run presenterm -e presentation.md # Generate backup PDF

Tips and Tricks

Quick Presentation Template

Create new presentation from template

cat > new-talk.md << 'EOF'

Talk Title

Subtitle

Your Name

Outline

1. Introduction
2. Main Content
3. Conclusion

Section 1

Content here

Thank You

Questions? EOF

Rapid Iteration

Use watch for live reload during development

(requires 'entr' or 'watchexec')

With entr

echo presentation.md | entr presenterm /_

With watchexec

watchexec -w presentation.md presenterm presentation.md

Export All Formats

#!/bin/bash

export-all.sh - Export presentation to all formats

PRESENTATION="$1" BASENAME="${PRESENTATION%.md}"

echo "Exporting $PRESENTATION..."

PDF

presenterm -e "$PRESENTATION" -o "${BASENAME}.pdf" echo "✓ PDF exported"

HTML

presenterm -E "$PRESENTATION" -o "${BASENAME}.html" echo "✓ HTML exported"

echo "All exports complete!"

Presentation Checklist

Pre-Presentation Checklist

Technical:

• Run validation: presenterm --validate-overflows slides.md
• Test code execution blocks
• Verify images load correctly
• Check font size visibility
• Test on actual presentation screen
• Export backup PDF

Content:

• Timing (practice run-through)
• Speaker notes complete
• Transitions smooth
• No typos
• Links working

Setup:

• Terminal font size readable
• Theme appropriate for venue
• Backup presentation on USB
• Power adapter
• HDMI/adapter cable

Troubleshooting

Images Not Displaying

Try different image protocols

presenterm --image-protocol iterm2 presentation.md presenterm --image-protocol kitty-local presentation.md presenterm --image-protocol ascii-blocks presentation.md # Fallback

Check image paths are relative or absolute

Ensure images exist

ls -la images/

Slides Overflow Terminal

Validate first

presenterm --validate-overflows presentation.md

Solutions:

1. Reduce content per slide

2. Increase terminal size

3. Use smaller font

4. Break into multiple slides

Code Execution Not Working

Ensure execution is enabled

presenterm -x presentation.md

Check script permissions

chmod +x script.sh

Test code block independently first

Theme Not Applied

List available themes

presenterm --list-themes

Check current theme

presenterm --current-theme

Specify theme explicitly

presenterm -t dark presentation.md

Check config file location

ls -la ~/.config/presenterm/config.yaml

Integration with Other Tools

With Git

Track presentations in version control

git init git add presentation.md images/ git commit -m "feat: add initial presentation"

Create tagged releases for different versions

git tag -a v1.0 -m "Conference version"

With make/just

justfile

present: presenterm -p slides.md

export: presenterm -e slides.md -o output.pdf presenterm -E slides.md -o output.html

validate: presenterm --validate-overflows slides.md presenterm --validate-snippets slides.md

all: validate export

With Continuous Integration

.github/workflows/validate-presentation.yml

name: Validate Presentation

on: [push, pull_request]

jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Install presenterm run: cargo install presenterm - name: Validate slides run: | presenterm --validate-overflows presentation.md presenterm --validate-snippets presentation.md - name: Export PDF run: presenterm -e presentation.md -o presentation.pdf - name: Upload PDF uses: actions/upload-artifact@v2 with: name: presentation path: presentation.pdf

Quick Reference

Basic usage

presenterm slides.md # View presentation presenterm -p slides.md # Presentation mode presenterm -t dark slides.md # With theme

Export

presenterm -e slides.md # Export to PDF presenterm -E slides.md # Export to HTML presenterm -e slides.md -o out.pdf # Custom output path

Validation

presenterm --validate-overflows slides.md presenterm --validate-snippets slides.md

Code execution

presenterm -x slides.md # Enable execution presenterm -X slides.md # Auto-replace execution

Themes

presenterm --list-themes # List themes presenterm --current-theme # Show current theme

Speaker notes

presenterm -P slides.md # Publish notes presenterm -l # Listen for notes

Help

presenterm --help # Full help presenterm --acknowledgements # Show acknowledgements presenterm -V # Version

Markdown Quick Reference

Slide separator

Headings

H1

H2

H3

Lists

• Bullet point
  • Nested bullet

1. Numbered item

Code blocks

code here
``` (triple backtick)

# Images
![Alt text](path/to/image.png)

# Tables
| Col1 | Col2 |
|------|------|
| A    | B    |

# Quotes
> Quote text

# Speaker notes
<!-- presenter notes
Notes here
-->

# Executable code
```bash +exec
command
``` (triple backtick)

# Rendered diagrams
```mermaid +render
graph TD
    A --> B
``` (triple backtick)

```d2 +render
A -> B
``` (triple backtick)

# Rendered formulas
```latex +render
\[ E = mc^2 \]
``` (triple backtick)

```typst +render
$ sum_(i=1)^n i = (n(n+1))/2 $
``` (triple backtick)

Resources

- Official repository: https://github.com/mfontanini/presenterm

- Documentation: https://github.com/mfontanini/presenterm/wiki

- Issue tracker: https://github.com/mfontanini/presenterm/issues

- Installation: brew install presenterm
 or cargo install presenterm

Summary

Primary directives:

- Write presentations in markdown

- Use presentation mode (-p
) for actual presentations

- Use advanced rendering: mermaid/d2 for diagrams, LaTeX/typst for formulas

- Include speaker notes for complex slides

- Validate before presenting

- Export to PDF/HTML for distribution

- Choose appropriate theme for venue/audience

- Keep slides simple and focused

- Test code execution and rendering blocks before presenting

Most common commands:

- presenterm -p slides.md
 - Present

- presenterm -e slides.md
 - Export PDF

- presenterm -t theme slides.md
 - Use theme

- presenterm --validate-overflows slides.md
 - Validate

- presenterm --list-themes
 - See themes

Advanced rendering:

- Mermaid diagrams:  ```mermaid +render
 (requires mermaid-cli)

- d2 diagrams:  ```d2 +render
 (requires d2)

- LaTeX formulas:  ```latex +render
 (requires typst + pandoc)

- Typst formulas:  ```typst +render
 (requires typst)