Slide decks are powered by astromotion, a thin Astro integration over Reveal.js with a Marp-inspired markdown syntax. astromotion is a separate package that you install and register beside the theme; the theme ships a deck stylesheet that matches the rest of the site. It derives its palette from the same brand tokens, so a re-branded site gets re-branded decks for free.
A deck is a .deck.mdx file under src/decks/. Each file becomes a route at
/decks/<name>, and slides are separated by --- thematic breaks. There’s a
complete, live example at /decks/astromotion — the
source for it lives at docs/src/decks/astromotion.deck.mdx.
Setup#
Install astromotion beside the theme and turn on decks:
import { defineConfig } from "astro/config";
import universityTheme from "astro-theme-university";
export default defineConfig({
integrations: [universityTheme({ decks: true })],
});
The theme registers astromotion with its own deck stylesheet and body font, and
appends astromotion’s remark plugins (slide splitting, @include, the _class
and ![bg] directives) to the markdown chain it owns. Pass an object to forward
astromotion options: routePrefix to mount decks somewhere other than /decks,
or theme for a site that layers deck CSS of its own over the theme’s:
universityTheme({ decks: { theme: "./src/decks/theme.css" } });
/* src/decks/theme.css */
@import url("astro-theme-university/styles/deck.css");
A site that registers astromotion() itself keeps doing so; decks then warns
and steps aside, and the site passes extraRemarkPlugins: deckRemarkPlugins to
the theme as before.
The deck stylesheet carries the brand tint scales and the slide classes below,
plus a full-bleed logo-slide class and reveal animations for closing logo
slides.
Composing decks with @include#
There is a single mechanism for pulling shared content into a deck: the
@include directive, written as a JSX comment.
{/* @include ./partials/intro.mdx */}
@include runs before slides are split, so a --- inside an included file
starts a new slide. The included file’s YAML frontmatter is stripped
automatically, which means the same file can render both as a standalone page
and as deck slides. Paths can be relative to the deck, or bare module specifiers
resolved from your node_modules. A package (a branding package, say) can then
ship shared partials that any deck includes without a relative path. Only .mdx
files can be included.
Two ways to organise reusable content#
The include mechanism is the same either way; what differs is where the fragment lives, and whether it has a life beyond the deck.
Content-collection topics#
On a course site, a topic is a content-collection entry that doubles as a deck
slide. It’s browsable on its own at /topics/<slug>/ and participates in the
content graph via its related edges. It’s pulled into a lecture by including
it from the collection directory:
{/* @include ../content/topics/variables.mdx */}
Reach for this when the fragment is genuinely course content — something a student might read standalone as well as see on a slide.
Deck partials#
When a fragment is pure slide furniture — an opening acknowledgement, a
presenter roster, a closing logo — it doesn’t belong in a content collection.
Keep it as a deck-only partial under src/decks/partials/ and include it by
relative path:
{/* @include ./partials/ack-country.mdx */}
This is the pattern for “master” decks that share a common opening and closing across several variants of a talk. Each master deck includes the same handful of partials and adds its own middle.
Slide features#
A quick reference — the example deck demonstrates each one:
- slide classes:
{/* _class: impact */}(available:impact,hero,quote,centered) - backgrounds:
,, - speaker notes: a fenced
```notesblock, authored in markdown (press S in the deck) - authoring comments: a fenced
```commentblock — prose for whoever edits the deck next, stripped from the rendered deck - code blocks: fenced code blocks get syntax highlighting automatically
- QR codes:

Co-locate background and other deck images under src/decks/assets/ and
reference them with a relative path. astromotion copies everything under
src/decks/ into the build output except source files (.mdx, .md, .svelte
and .css), so co-located assets resolve in production. Images elsewhere in
src/ won’t be copied.
Artwork behind every impact slide#
 dresses one slide at a time. To give every impact slide the same
full-bleed artwork instead of the flat brand fill, set it once in your deck
stylesheet. For an asset sitting beside that stylesheet, declare
background-image on the class directly, so your bundler hashes and
base-prefixes it like any other deck asset:
.reveal section.impact {
background-image: url("./assets/impact-bg.avif");
}
For a URL that needs no bundler resolution — a public/ path, an absolute
URL, a data URI — use the custom property instead:
:root {
--at-deck-impact-bg-image: url("/decks/impact-bg.avif");
}
(The two forms exist for the same reason as astromotion’s whiteboard background.
A relative url() inside a custom property resolves against wherever the
var() is used, not where it’s declared. lightningcss rejects that as
ambiguous.)
The image is sized like a cover background, and nothing dims or scrims it.
Supply artwork that keeps the slide’s text legible: a low-contrast ground, or a
mostly-empty field with the motif kept to a corner. Which ink that text takes
depends on the brand colour (white on a dark --at-primary, near-black on a
light one; see --at-on-primary), so match the artwork to it.
The hero scrim#
A hero slide dims its background image behind the title with a scrim that runs
from 20% black at top to 80% at bottom. On screen it is a CSS gradient; in a PDF
(an astromotion-pdf export, or printing the deck) it becomes a tiny PNG with
an alpha channel, a 1x256 ramp stretched over the slide. The two look the same.
They differ because Chrome writes a gradient whose alpha varies as a shading
behind a luminosity soft mask, which PDFium (Chrome’s own PDF viewer), pdf.js
and iOS Safari mishandle, while an image with an alpha channel is the one kind
of transparency every PDF renderer agrees on.
Each has its own override. --at-deck-hero-scrim takes any CSS background and
restyles the screen scrim; --at-deck-hero-scrim-print restyles the PDF one and
should be a raster image with alpha too:
:root {
--at-deck-hero-scrim: linear-gradient(to top, rgb(0 0 0 / 70%), transparent);
--at-deck-hero-scrim-print: url("/decks/hero-scrim.png");
}
Keep translucent gradients, mask-image and blend modes out of the print
override: the browser shows the slide you designed, but each PDF viewer draws it
differently.
Table headers#
A table marks its header row with weight and a single rule in the brand colour,
on the web and in decks alike. Decks draw the rule from their own token rather
than the web side’s --at-table-header-rule, and at a softer strength: on a
near-black slide a full-strength brand line competes with the heading above it.
:root {
--at-deck-table-header-rule: rgb(from var(--at-primary) r g b / 55%);
}
Every th is set semibold, not just the ones in thead. A matrix table has
body rows carrying <th scope="row"> labels — think a grid of counts with
words down the side and across the top. Its two header axes mean the same thing,
so both carry the same weight; the rule is what marks a true header row.