Skip to main content

Lecture decks

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:

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

![bg](…) 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.