Introduction

This guide teaches you how to use presenterm. At this point you should have already installed presenterm, otherwise visit the installation guide to get started.

Quick start

Download the demo presentation and run it using:

git clone https://github.com/mfontanini/presenterm.git
cd presenterm
presenterm examples/demo.md

Presentations

A presentation in presenterm is a single markdown file. Every slide in the presentation file is delimited by a line that contains a single HTML comment:

<!-- end_slide -->

Presentations can contain most commonly used markdown elements such as ordered and unordered lists, headings, formatted text (bold, italics, strikethrough, inline code, etc), code blocks, block quotes, tables, etc.

Introduction slide

By setting a front matter at the beginning of your presentation you can configure the title, sub title, author and other metadata about your presentation. Doing so will cause presenterm to create an introduction slide:

---
title: "My _first_ **presentation**"
sub_title: (in presenterm!)
author: Myself
---

All of these attributes are optional and should be avoided if an introduction slide is not needed. Note that the title key can contain arbitrary markdown so you can use bold, italics, <span> tags, etc.

Multiple authors

If you're creating a presentation in which there's multiple authors, you can use the authors key instead of author and list them all this way:

---
title: Our first presentation
authors:
  - Me
  - You
---

Slide titles

Any setext header will be considered to be a slide title and will be rendered in a more slide-title-looking way. By default this means it will be centered, some vertical padding will be added and the text color will be different.

Hello
===

[!note] See the themes section on how to customize the looks of slide titles and any other element in a presentation.

Ending slides

While other applications use a thematic break (---) to mark the end of a slide, presenterm uses a special end_slide HTML comment:

<!-- end_slide -->

This makes the end of a slide more explicit and easy to spot while you're editing your presentation. See the configuration if you want to customize this behavior.

If you really would prefer to use thematic breaks (---) to delimit slides, you can do that by enabling the end_slide_shorthand options.

Colored text

span HTML tags can be used to provide foreground and/or background colors to text. There's currently two ways to specify colors:

• Via the style attribute, in which only the CSS attributes color and background-color can be used to set the foreground and background colors respectively. Colors used in both CSS attributes can refer to theme palette colors by using the palette:<name> or p:<name syntaxes.
• Via the class attribute, which must point to a class defined in the theme palette. Classes allow configuring foreground/background color combinations to be used across your presentation.

For example, the following will use ff0000 as the foreground color and whatever the active theme's palette defines as foo:

<span style="color: #ff0000; background-color: palette:foo">colored text!</span>

Alternatively, can you can define a class that contains a foreground/background color combination in your theme's palette and use it:

<span class="my_class">colored text!</span>

[!note] Keep in mind only span tags are supported.

Font sizes

The kitty terminal added in version 0.40.0 support for a new protocol that allows TUIs to specify the font size to be used when printing text. presenterm is one of the first applications supports this protocol in various places:

• Themes can specify it in the presentation title in the introduction slide, in slide titles, and in headers by using the font_size property. All built in themes currently set font size to 2 (1 is the default) for these elements.
• Explicitly by using the font_size comment command:

# Normal text

<!-- font_size: 2 -->

# Larger text

Terminal support for this feature is verified when presenterm starts and any attempt to change the font size, be it via the theme or via the comment command, will be ignored if it's not supported.

Key bindings

Navigation within a presentation should be intuitive: jumping to the next/previous slide can be done by using the arrow keys, hjkl, and page up/down keys.

Besides this:

• Jumping to the first slide: gg.
• Jumping to the last slide: G.
• Jumping to a specific slide: <slide-number>G.
• Exit the presentation: <ctrl>c.

You can check all the configured keybindings by pressing ? while running presenterm.

Configuring key bindings

If you don't like the default key bindings, you can override them in the configuration file.

Modals

presenterm currently has 2 modals that can provide some information while running the application. Modals can be toggled using some key combination and can be hidden using the escape key by default, but these can be configured via the configuration file key bindings.

Slide index modal

This modal can be toggled by default using control+p and lets you see an index that contains a row for every slide in the presentation, including its title and slide index. This allows you to find a slide you're trying to jump to quicklier rather than scanning through each of them.

Key bindings modal

The key bindings modal displays the key bindings for each of the supported actions and can be opened by pressing ?.

Toggle visual grid

Press uppercase T by default to toggle the layout grid. This is useful when using a column layout and trying to understand how wide each column is. See this PR for more details.

Hot reload

Unless you run in presentation mode by passing in the --present parameter, presenterm will automatically reload your presentation file every time you save it. presenterm will also automatically detect which specific slide was modified and jump to it so you don't have to be jumping back and forth between the source markdown and the presentation to see how the changes look like.