presenterm Documentation

presenterm is a tool that allows you to create presentations using Markdown format and execute them directly from your terminal.

Key features include:

• Support for images and animated GIFs.
• Highly customizable themes.
• Code syntax highlighting.
• Ability to export presentations into PDF format.

Presenterm follows a multi-stage pipeline to transform Markdown files into terminal output:

1. Parsing: The Markdown file is parsed using the comrak crate into an Abstract Syntax Tree (AST). This AST is then flattened into a list of MarkdownElements to simplify processing.
2. Building the Presentation: The flattened MarkdownElements and a chosen theme are processed to create a Presentation. A Presentation consists of multiple slides, where each slide contains a sequence of render operations (primitives like rendering text, clearing the screen, or setting colors).
3. Rendering: The rendering engine iterates through the render operations of a slide and executes them using the crossterm crate. This stage handles terminal-specific tasks like word wrapping and margin management based on the current screen size.

You can convert presentations into PDF files using the --export-pdf flag. This feature requires the weasyprint tool to be installed on your system.

Prerequisites

Install weasyprint following their official installation instructions. If you use a separate virtual environment for weasyprint, ensure it is activated before running presenterm.

Usage

Run presenterm with the --export-pdf parameter followed by your markdown file. By default, the output is placed in the same directory as the source file with a .pdf extension. Use the --output flag to specify a custom destination.

You can specify a theme directly within your presentation's markdown file using YAML front matter. There are four ways to configure this:

By name

Use a built-in theme name to override defaults or CLI options.

Light/Dark detection

Define different themes for light and dark terminal variants.

By path

Reference a custom theme file located on your filesystem using a YAML path.

Overrides

Partially or completely override specific theme properties (like colors) without creating a new file. Overrides are reloaded whenever you save the presentation file.

---
theme:
  # By name
  name: dark

  # Light/Dark detection
  light: light
  dark: dark

  # By path
  path: /home/me/Documents/epic-theme.yaml

  # Overrides
  override:
    default:
      colors:
        foreground: "beeeff"
---

When using the #image() function inside a typst code block, you must follow these rules:

1. Use absolute paths: e.g., #image("/image1.png").
2. Path relativity: The absolute path is considered relative to the directory where your presentation file is located. You can reference files in the same directory or subdirectories of the presentation, but not parent directories.

You can control the size of rendered Mermaid diagrams using two methods:

1. Global Scaling: Adjust the mermaid.scale configuration parameter for a baseline size across all diagrams.
2. Per-snippet Width: Use the +width:<number>% attribute within the code snippet to set a specific width relative to the window. This preserves the aspect ratio.

Best Practice: Set a reasonable mermaid.scale first to ensure images are large enough, then use +width for fine-tuning to avoid blurry images caused by upscaling small images.

sequenceDiagram
    Mark --> Bob: Hello!
    Bob --> Mark: Oh, hi mark!

By default, slides are delimited by a specific HTML comment. To use thematic breaks (---) instead, you must enable the end_slide_shorthand option in your configuration.

<!-- end_slide -->

Elements like code blocks, slide titles, intro slide components (title, subtitle, author), and tables support alignment.

Left/Right Alignment

Use alignment: left or alignment: right with a margin property. Margins can be defined as:

• Fixed: A specific number of characters.
• Percent: A percentage of the total terminal columns (recommended for responsiveness).

Center Alignment

Use alignment: center with two optional properties:

• minimum_size: The minimum width of the element (useful for code blocks to extend background color).
• minimum_margin: The minimum margin to keep on both sides of the text.

Options are configuration parameters that can be set in two ways:

1. In the global configuration file under the options key.
2. In a specific presentation's front matter under the options key. Using front matter allows you to customize the behavior of a single presentation without affecting others.