Polylux Documentation

Polylux is a package for the Typst typesetting system designed to create presentation slides. It functions similarly to the beamer package in LaTeX, where each slide typically corresponds to one PDF page. You can present these slides using the slideshow mode of most PDF viewers (often by pressing F5).

Key features include:

• Elegant typesetting via Typst.
• Fully customizable slides.
• Dynamic slides (overlays) for (dis-)appearing content.
• Available templates to accelerate setup.

The #show: later rule only affects the content within its immediate surrounding scope. If you are working with multiple nested or adjacent scopes and encounter layout issues or unexpected interactions, you can use the strand argument to isolate them.

By providing a unique strand integer to later.with(strand: n), you create independent reveal sequences. Every strand works independently of every other.

#[
  this is scope 1
  #show: later
  still scope 1
]

#[
  this is scope 2
  #show: later.with(strand: 2)
  still scope 2
]

Polylux themes are optional abstractions that simplify slide preparation. While you can use Polylux without them, themes follow a standard convention to provide a consistent user experience.

Key components of the theme convention include:

1. Module Import: Themes are located in the themes module.
2. Initialization Function: Themes provide an initialization function (conventionally ending in -theme) used with a #show: rule to configure presentation-wide settings like aspect-ratio.
3. Custom Slide Functions: Instead of calling the core #polylux-slide function directly, themes provide wrapper functions (conventionally #title-slide and #slide) that handle slide creation and layout automatically.

You can specify a range of numbers using an interval. This is represented as a dictionary with the following keys:

• beginning: The start of the interval (inclusive).
• until: The end of the interval (exclusive).

Intervals can be bounded (both keys present) or half-bounded (only one key present).

When defining custom slide functions (like title-slide or slide), you must wrap the content you produce in the #polylux-slide function. Failing to do this will cause Polylux features like #uncover to break.

• If you are building a theme as part of the Polylux package, use the qualified function: logic.polylux-slide.
• For regular slides, it is convention to name the function slide and have it accept arbitrary content as a positional parameter.

When creating subslides, you can control whether content should occupy space when it is not being displayed. Polylux provides two primary functions to handle this:

1. #only: Use this when the content should not exist on the slides where it is not specified. The layout will adjust as if the content were never there.
2. #uncover: Use this when the content should be invisible but still occupy its space on the slides where it is not specified. This prevents layout shifts when the content eventually appears.

Choose #only if you want the layout to be dynamic, or #uncover if you want to reserve space to prevent elements from jumping around as they appear.

The #only and #uncover functions control when specific content is visible across a sequence of subslides. Both functions accept two positional arguments:

1. Description: A rule or index specifying which subslides the content should appear on.
2. Content: The actual content to be displayed.

Difference in behavior

• #only ensures the content is shown only on the specified subslides and is hidden on all others.
• #uncover ensures the content is present on all subslides in the sequence, but is only visible (uncovered) on the specified subslides.

Syntax Tip

You can use Typst's syntactic sugar by placing the content block after the function call for better readability.

Dynamic content in Polylux is controlled by specifying which subslides a piece of content should appear on. The total number of subslides (PDF pages) generated for a logical slide is equal to the maximum subslide index referenced by any dynamic command within that slide.

Example Calculation: If a logical slide contains these commands:

• Show something on subslides 1 and 3
• Show something from subslide 2 to subslide 4
• Show something until subslide 6

The resulting logical slide will produce 6 PDF pages.

A Polylux theme is centered around an initialization function (conventionally named [theme-name]-theme). This function follows the Typst template pattern: it accepts keyword arguments for configuration options and a single positional content argument for the rest of the document.

Inside this function, you should:

1. Set page parameters (like aspect ratio).
2. Define global styles (like text color, font, or background color).

Example structure:

let science-slam-theme(aspect-ratio: 16/9, background-color: black, doc) = {
  set page(aspect-ratio: aspect-ratio, background-color: background-color)
  set text(font: "sans-serif", size: 20pt, fill: white)
  doc
}

Polylux provides dynamic content (also known as overlays). This allows you to create effects where parts of a slide appear or disappear, or text colors change, without manually duplicating the entire slide.

When you use overlay features, Polylux automatically generates the necessary additional PDF pages to simulate these changes, allowing you to maintain a single source of truth for your content while presenting different states of that content.

Polylux provides "higher level" helper functions that operate on larger pieces of content by leveraging the underlying #only and #uncover primitives. These helpers are designed to simplify recurring presentation patterns.

Key categories of helper functions include:

• Successive Revelation: Use #pause and #one-by-one (and related variants) to reveal content incrementally.
• Content Substitution: Use #alternatives (and its variants) to swap between different pieces of content.