Syntax

Deck files

A deck is one .astro or .mdx file. Both formats produce an ordered list of pages and use the same theme layout system.

Astro pages

Astro decks import Page and contain only top-level <Page> components:

---
import Page from "@deckup/astro/page";
---

<Page title="Presentation title" layout="cover">
  <h1>Presentation title</h1>
</Page>

<Page title="Content">
  <p>Slide content</p>
</Page>

MDX pages

Horizontal rules split MDX decks into pages:

# Cover title

Cover subtitle

---

# Content slide

- First point
- Second point

Deckup wraps each segment in a generated Page component. Empty pages are invalid, so do not use adjacent rules or a trailing rule without content.

Layout declarations

Deckup assigns cover to page 1 and default to every later page unless the page declares another layout.

In Astro, set layout directly on Page:

<Page title="Two columns" layout="two-column">
  <h1>Two columns</h1>
</Page>

The value must be a static, non-empty string. Expressions and shorthand attributes are invalid, and a Page may not declare multiple layout attributes. When using a JSX spread, place it before layout; a spread after the explicit layout is rejected because it could overwrite the analyzed value at runtime.

In MDX, declare the layout with an import-free PageMeta marker:

<PageMeta layout="two-column" />

PageMeta is an import-free Deckup marker, not a runtime component. A page may contain at most one PageMeta declaration. It must be the first meaningful direct child; whitespace and non-rendering comments may precede it. The marker must be self-closing and may contain exactly one static, non-empty layout string attribute. Expressions, spreads, unknown attributes, children, and paired tags are invalid. PageMeta is reserved and is removed before content renders. Layout IDs start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.

Named slots

Target a named region with Astro’s standard slot attribute:

<Page title="Two columns" layout="two-column">
  <h1>Two columns</h1>
  <p slot="left">Left side</p>
  <p slot="right">Right side</p>
</Page>

The same syntax works on JSX elements in MDX. Available layout IDs and slot names depend on the selected theme.

Deck-level themes

In MDX, set static theme metadata in YAML frontmatter:

---
title: Product update
theme: minimal
---

In Astro, declare a static top-level constant in the frontmatter script:

---
const theme = "minimal";
---

The value must be a static string. Theme precedence is deck metadata, then deckup.config.*, then default.