Skip to content

Manifest reference

The deck DSL you use in deck.py. Everything here is imported from the top-level inkflow package:

from inkflow import Deck, Slide, Image, Video, TextBox, Overlay, Align, VAlign, Inline

Refer to the Enums reference page for the shared value types used across this section. For the implemented animation and transition types, see the Animations and Transitions reference pages.

Deck dataclass

The top-level presentation container.

Define a main() -> Deck function in deck.py; inkflow calls it at serve time.

Deck → Slide inheritance:

  • transition, font_size, overlays — override: a slide value replaces the deck default; None on the slide inherits. If both are None, the theme default is used.
  • style / extra_style — additive: Deck.style is emitted first, then Slide.extra_style; the slide CSS wins on equal-specificity rules via cascade order.
  • theme, mode, embed_fonts, title — deck-only; no per-slide override.
def main() -> Deck:
    return Deck(
        transition=transitions.Crossfade(),
        mode=ColorMode.DARK,
        slides=[...],
    )

slides class-attribute instance-attribute 

slides: list[Slide] = field(default_factory=list)

The ordered slide list.

transition class-attribute instance-attribute 

transition: Transition | None = None

Default transition for all slides. None defers to the theme's default.

overlays class-attribute instance-attribute 

overlays: Sequence[Overlay] | None = None

Chrome composited on top of every slide, in paint order. None defers to the theme's overlays; [] means none.

theme class-attribute instance-attribute 

theme: Theme = field(default_factory=Builtin)

The deck's theme. Defaults to the built-in Catppuccin theme. Subclass Theme (or Builtin) and pass an instance to restyle the deck.

mode class-attribute instance-attribute 

mode: ColorMode | None = None

Dark or light color mode. None defers to the theme's mode.

style class-attribute instance-attribute 

style: Content = None

CSS injected into every slide. A bare str is a file path; Inline(...) is a literal CSS string.

font_size class-attribute instance-attribute 

font_size: int | None = None

Base font size for zone content, in px. None defers to the theme.

embed_fonts class-attribute instance-attribute 

embed_fonts: bool = True

Auto-discover and embed the fonts used in slides. Set False to opt out.

title class-attribute instance-attribute 

title: str | None = None

Presentation title, used for the browser tab, static build page, and PDF metadata. None infers a title from the project directory name.

effective_mode property 

effective_mode: ColorMode

Resolved color mode: the deck value, else the theme's default.

effective_font_size property 

effective_font_size: int

Resolved base font size: the deck value, else the theme's default.

effective_transition property 

effective_transition: Transition

Resolved default transition: the deck value, else the theme's default.

effective_overlays property 

effective_overlays: Sequence[Overlay]

Resolved default overlays: the deck value, else the theme's.

Slide dataclass

A single slide.

src is a reference to an SVG file. Any SVG can define named zones, and if it does, md/zones inject content into them — whether that SVG is a one-off slide in slides/ or a reusable layout in layouts/ shared across many slides.

Markdown content can link to another slide by id with the slide: scheme ([overview](slide:overview)); clicking it jumps to that slide with a cut transition. Unresolved ids are silently ignored.

# One-off SVG with animations, no zones
Slide("title", animations=[animations.FadeIn("headline")])

# Reusable layout with Markdown-filled zones
Slide("content", md="bullets", zones={"media": Image("photo.jpg")})

src instance-attribute 

src: str

Reference to the slide's SVG file. A bare name (e.g. "content") is looked up in slides/ first, then searched across layouts (project → theme → built-in); prefix with local:, theme:, or builtin: to pin to one of those directly.

id class-attribute instance-attribute 

id: str | None = None

Stable identifier, used as the slide: link target. Auto-inferred from the .md filename stem or the src stem when unset. Must be unique across the deck; collisions are resolved by appending -2, -3, …

md class-attribute instance-attribute 

md: Content = None

Path to a .md file, or Inline("...") for inline Markdown. Content is routed into src's zones, if it defines any.

zones class-attribute instance-attribute 

zones: dict[str, ZoneContent] = field(default_factory=dict)

Per-zone overrides. Keys are zone names without the zone- prefix; values are ZoneContent (inline Markdown str, TextBox, or Media).

animations class-attribute instance-attribute 

animations: list[Cue] = field(default_factory=list)

Animations and PlayVideo cues for this slide. They run after any markdown reveals in the content.

transition class-attribute instance-attribute 

transition: Transition | None = None

Transition into this slide. None inherits the deck default.

overlays class-attribute instance-attribute 

overlays: Sequence[Overlay] | None = None

Chrome composited on top of this slide, in paint order. None inherits the deck's overlays; [] opts this slide out of all chrome.

extra_style class-attribute instance-attribute 

extra_style: Content = None

CSS appended to the deck style for this slide. A bare str is a file path; Inline(...) is a literal CSS string.

title class-attribute instance-attribute 

title: str | None = None

Optional slide title. Auto-inferred from the filename or a leading # heading when unset.

notes class-attribute instance-attribute 

notes: Content = None

Speaker notes rendered as Markdown. A bare str is a file path; Inline("...") is literal content. Concatenated with any ::notes:: marker in the Markdown file.

visible class-attribute instance-attribute 

visible: bool = True

When False, the slide is excluded from the presentation entirely.

font_size class-attribute instance-attribute 

font_size: int | None = None

Per-slide base font size in px. None inherits Deck.font_size.

Overlay dataclass

An SVG composited on top of the finished slide.

Deck(
    overlays=[Overlay("footer"), Overlay("logo")],
    slides=[
        Slide("title.svg", overlays=[]),   # no chrome on the title
        Slide("content", md="intro.md"),   # inherits the deck's two
    ],
)

List order is paint order. Resolution is Slide.overlays → Deck.overlays → Theme.overlays, each an override: None inherits, [] means none.

An overlay may set inkflow:parent to another overlay, which composites behind it inside the overlay group while the group as a whole stays on top of the slide. That is how a shared brand bar is extended per deck without duplicating it.

src instance-attribute 

src: str

Reference to the overlay SVG. A bare name (e.g. "footer") is searched project overlays/ → theme overlays/ → built-in overlays/; prefix with local:, theme:, or builtin: to pin one, or use a relative or absolute path. Layouts and overlays are separate namespaces, so a bare name never resolves to a layout.

Image dataclass

Bases: _MediaBase

An image asset for injection into a zone.

Pass it as a value in a slide's zones dict to inject it into that zone.

Slide("content", md="bullets", zones={"media": Image("photo.jpg")})

Video dataclass

Bases: _MediaBase

A video asset for injection into a zone, with playback control.

Pass it as a value in a slide's zones dict to inject it into that zone. To start a clip on a step rather than on load, add an animations.PlayVideo cue for its zone.

Slide(
    "media-right",
    md="feature",
    zones={"media": Video("demo.mp4", autoplay=True, loop=True)},
)

controls class-attribute instance-attribute 

controls: bool = True

Show the browser's native playback controls.

autoplay class-attribute instance-attribute 

autoplay: bool = False

Start playing when the slide loads.

muted class-attribute instance-attribute 

muted: Muted = Muted.AUTO

Audio muting policy. AUTO mutes only when autoplay is set, so the browser never blocks autoplay by default; ON always mutes; OFF never mutes.

loop class-attribute instance-attribute 

loop: bool = False

Restart from start when the clip ends.

poster class-attribute instance-attribute 

poster: str | None = None

Path/URL of a still image shown before playback begins.

start class-attribute instance-attribute 

start: float | None = None

Trim-in time in seconds (temporal trim, distinct from the spatial fit/align crop).

end class-attribute instance-attribute 

end: float | None = None

Trim-out time in seconds.

TextBox dataclass

Explicit text content and alignment for a named zone in an SVG slide.

Pass it as a value in a slide's zones dict to inject HTML into that zone with alignment control. Each alignment param defaults to None, meaning "defer to the layout's CSS variable".

TextBox(text="<p>My content</p>", align=Align.CENTER, valign=VAlign.CENTER)

text class-attribute instance-attribute 

text: str | None = None

HTML content to inject into the zone.

align class-attribute instance-attribute 

align: Align | None = None

Horizontal text alignment. None defers to the layout CSS variable.

valign class-attribute instance-attribute 

valign: VAlign | None = None

Vertical alignment of the content block. None defers to the CSS variable.

padding class-attribute instance-attribute 

padding: float | None = None

Inner padding in SVG user units. None defers to the CSS variable.

Inline

Bases: str

Marks a string as literal content rather than a file path.

Fields typed as Content interpret a bare str as a file path to read. Wrapping the value in Inline(...) signals that the string itself is the content — rendered as Markdown for notes/md, or used as CSS for style/extra_style.

Inline subclasses str, so isinstance(Inline("x"), str) is True and it compares equal to its content. The distinction only matters at pipeline resolution time.

Slide("content", notes=Inline("Talk through the diagram."))
Slide("content", md=Inline("# Quick slide\n\nNo .md file needed."))
Deck(style=Inline("rect { fill: red; }"))

Content module-attribute 

Content: TypeAlias = 'str | Inline | None'

A field that accepts either a file path or literal content.

A bare str is treated as a path to read; an Inline value is used verbatim. None means "nothing". Used by Slide.md, Slide.notes, Slide.extra_style, and Deck.style.

ZoneContent module-attribute 

ZoneContent = str | Media | TextBox

A value accepted in Slide.zones.

A str is rendered as inline Markdown; a TextBox gives explicit alignment and padding control; an Image or Video injects media.