Presentations

Presentation adds presenting to a document. Deck uses that same capability with a layout designed for authored slides. Articles and decks remain different kinds of pages, each with two views: a scrolling Markdown page and a browser presentation. Read is the default on every screen. Both views use the same content and mounted figures, so edits and local parameter changes carry across. The presentation reflows the document for the screen; it does not summarize or duplicate it.

Choose the page layout

Use an article for a continuous argument and a deck for a sequence of authored frames. Presentations is the navigation label; /slides/ and src/content/slides/ stay the default route and storage path.

---
import Deck from '@alkemdotdev/alkemist-components/deck';
import Slide from '@alkemdotdev/alkemist-components/slide';
---

<Deck title="An experiment">
  <Slide title="The question"><p>What changes when the source moves?</p></Slide>
  <Slide title="The observation"
    ><p>Keep the evidence beside the claim.</p></Slide
  >
</Deck>

Types (PresentationProps, DeckProps, SlideProps) come from those same entries. Presentation also accepts layout="deck"; Deck is the convenient explicit form. Both accept embedded for independent examples in a host page. Compare the layouts live.

Existing Slides imports remain a deck compatibility entry. format: slides and alkemist({ slides: true }) still work; use format: deck and presentations: true for new work. Do not give the two integration options conflicting values. Nothing requires renaming existing content or URLs.

Present an existing post

Add present: true to a post’s frontmatter. The site’s Blog route and the generated starter support this directly:

---
title: An experiment
description: What changed when we moved the source.
date: '2026-09-15'
present: true
---

Start with the question and its context.

## Observation

Show the evidence here.

## Limits

Explain what this experiment cannot establish.

H2 headings begin presentation sections; an ordinary top-level --- can add a boundary within a longer section. Subheadings remain with their parent section. The title, lead, and cover are the introduction. Rules remain visible in Read, and footnotes retain their normal links and a single reference list. MDX posts keep explicit component imports.

Try One document, two views. A custom content route can use the same compiler with present: true and wrap its rendered <Content /> in <Presentation title={entry.data.title}>. Include any route-owned title or cover inside a section with data-alk-slide if it should appear in Present. Add present: z.boolean().default(false) to the collection schema. The integration requires presentations: true.

Start with Markdown

Add the integration option, then create src/content/slides/ and a document with format: deck. A top-level rule begins the next slide. Use .md for ordinary Markdown and .mdx when a deck needs a component.

import alkemist from '@alkemdotdev/alkemist-astro';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [alkemist({ presentations: true })],
});

---
title: First talk
description: A short browser presentation.
format: deck
incremental: true
---

# A question worth showing

Start with Markdown.

<!-- notes: Introduce the question before describing the work. -->

---

# One clear observation

- State the observation.
- Show the evidence.

The incremental option enables ordinary list progression for the deck. <Step> gives MDX authors an explicit progression point. Reading output shows all steps.

Let the content choose the layout

Slides infer a compact layout from their content: a title gets room, an image beside prose becomes a split, a widget becomes a media slide, and a quote remains quiet. You do not need frontmatter layout names for ordinary decks. When a real slide needs a different treatment, add a comment immediately before it:

<!-- layout: split -->

## A picture and an explanation

![A descriptive image.](./figure.png)

Keep the source and the interpretation together.

MDX uses a JSX comment: {/* layout: split */}. Available layouts are title, split, media, quote, and content; unknown values produce a build-time authoring error rather than changing a deck silently. Deck reading keeps authored slide boundaries as padded surfaces with natural content height. Articles retain continuous prose. Present uses the same responsive stage in both cases; the content and mounted widgets are unchanged.

Share the site theme

The site and slides share Neutral, Paper, Chalk, and Blueprint. Named styles are separate from Light/Dark/System color mode. A deck inherits the site by default; override a particular talk in frontmatter or try a scoped choice under Tools → Appearance. These controls change the current deck, while the site header changes the site preference. aspect: auto uses the available viewport; use a fixed aspect only when a venue requires it.

theme: blueprint # inherit, default, paper, chalk, or blueprint
colorScheme: dark # inherit, system, light, or dark
transition: slide # none, fade, or slide
aspect: '16:9' # auto, 16:9, or 4:3

Themes expose --alk-slide-background, --alk-slide-foreground, --alk-slide-accent, --alk-slide-font, and --alk-slide-heading-font. Site authors can set these variables or use a deck class/style for a custom surface without replacing the semantic slide structure.

For example, add class: research-talk to a deck and put this in your site stylesheet:

.research-talk {
  --alk-slide-accent: #7654b8;
  --alk-slide-heading-font: var(--alk-serif);
}

Content is laid out first, then text fitting makes small adjustments within a readable size. Long tables, code, or unusually dense slides remain scrollable; split the material across slides when it needs more room.

Present from the browser

Present opens at the section you are reading and fills the page area with the slide. The top and bottom bars start hidden. Use the small Show presentation controls button in the bottom-right corner, or press C, to reveal them. The bars overlay the slide without resizing its figures; use the same button or shortcut to hide them again. Present leaves browser fullscreen under your control.

Back to reading or Escape returns to the current section; staying on the same slide restores your prior reading position. The same figures remain mounted through both transitions. In Read, Tools → Contents jumps between sections. In Present, the slide count opens Overview, with selectable cards containing images and audience-facing text. The bottom controls move between slides or individual steps, and the slide picker jumps directly to a section.

Ordinary heading links open in Read. Presentation links with #/slide-id open directly in Present. Copy current link shares the current section in the current mode. Component authors can request view="present" when a page should explicitly open in presentation mode; audience and receiver windows always do so.

Tools groups appearance, presenter views, presentation controls, sharing, and keyboard help. Timed advance starts only when requested and stops when the page is hidden, the overview opens, blackout begins, or the deck ends. Media never begins playing automatically.

Focus the slide and use arrow keys or Space to advance. C shows or hides controls, O opens Overview, S opens Speaker view, B toggles Blackout, L toggles the pointer, F toggles Fullscreen, and ? shows keyboard help. Escape closes an overlay or leaves the presentation. Browser shortcuts and interactive figure controls keep their normal behavior. Touch users can swipe the slide background and tap the corner button for controls.

Use Tools → Print to load lazy figures and capture current GPU views before opening the browser print dialog. Speaker view uses a separate window, so allow that window if your browser blocks it.

Use the forms Markdown already has

Headings, lists, images, links, tables, math, fenced code, and footnotes use their usual Markdown syntax. The integration also accepts GitHub-style alerts and mermaid fences in a deck. These forms render through the configured Markdown pipeline; they do not require a second slide-specific language.

Use an HTML comment beginning notes: for a short presenter note in Markdown, as in the example above. MDX uses <SpeakerNotes> because MDX comments are JSX comments. Notes remain in distributed HTML, so never place private material in them.

Add a figure in MDX

When slide authoring is enabled, Alkemist supplies the built-in component names Model, Chart, Shader, Math, Code, Audio, Video, Midi, Note, Step, SpeakerNotes, and Diagram when they are not already bound by an explicit import or local declaration. Widgets keep their existing props.

---
title: Field notebook
description: A chart with a note.
format: deck
---

# A signal

<Chart
  id="signal-chart"
  src="/test/oscillation.csv"
  type="line"
  x="time"
  y="position"
  title="Damped oscillator"
  description="A synthetic analytic trajectory."
  sample
/>

<Note for="signal-chart">The CSV is a deterministic teaching fixture.</Note>

id is optional on widgets. Give a figure an ID when attaching a Note; the note text appears beside its target in reading and presentation views. A missing target is an authoring error. Deck is also available to an Astro page through @alkemdotdev/alkemist-components/deck; pass a title, optional description, theme, transition, aspect, and compiled slide sections in its default slot.

Explore live parameters

A component’s ordinary props set its initial values. parameters exposes its supported live controls; an array exposes only the named subset.

<Shader frequency={9} angle={24} parameters />
<Chart {...chartProps} parameters={['ink', 'grid', 'zoom']} />
<Model {...modelProps} parameters={['view', 'wireframe']} />

Focus in a figure heading enlarges the same figure. Escape returns to the deck without resetting values. Inputs, charts, and model gestures keep their own keyboard and touch behavior. Opening Focus stops timed advance. The parameter guide lists supported controls and the Focus component adds the same behavior to ordinary pages.

Publish and check a talk

The starter includes src/content/slides/first-talk.md. The demo includes:

• Look closer combines prepared chart data, image exports, model parameters, and Focus.
• A figure you can question demonstrates live parameters and focused figures with the inherited site theme.
• Ready for the room rehearses audience views and native browser tools.
• Working with a signal uses plain Markdown, equations, code, footnotes, and Mermaid.
• A field notebook in motion combines Chart, Model, Shader, and figure notes.
• Listening to the fixture exercises Audio, Video, and the MIDI editor.
• A page can change its posture shows inferred title, image/prose, list, quote, table, and code layouts.

Read and Present share the same widget instances. Every screen defaults to Read. Speaker view is available for standalone decks; embedded decks keep independent navigation within their host page. Article reading uses --alk-document-width (760px by default); deck reading uses --alk-deck-width (1100px by default).

The slide index and route exclude draft: true, just as Blog does. Test the reading route and presentation controls at desktop and phone widths. Exercise backward steps, widget focus, media pause on slide change, resize, and a no-JavaScript reading load before publishing. Browser presentation does not establish a verified PDF or video export; treat those as separate artifact work.

Use the browser’s presentation facilities

Tools → Audience window opens a clean, synchronized view. Move it to a projector or second display and use Fullscreen there. The original deck controls slide position, progressive steps, and blackout; interactive widget settings are local to each display. Reloading the audience window rejoins the current session. Speaker notes are not sent through the audience synchronization protocol, though authored notes remain in the published HTML.

Choose display lists attached screens when the browser supports and permits it. Selecting one requests fullscreen for the current deck on that display. Display access is requested only when you click the control. If access is denied, move the audience window manually.

Floating speaker notes opens a compact, always-on-top notes window in supporting desktop browsers. It has the current and upcoming title, elapsed time, and Previous/Next/Blackout controls. It leaves live figures in the deck. The regular Speaker view remains available when floating windows are unsupported.

Keep display awake is opt-in. Its label reflects whether the browser granted or released the lock. Hidden pages, reading mode, and blackout release it; returning to an eligible presentation reacquires an opted-in lock. Battery, browser, and operating-system policy can still prevent it.

The native Screen Wake Lock, Window Management, and Document Picture-in-Picture facilities have different support and permission requirements. Controls appear only when their API is available; permission denial keeps the local deck usable. These facilities need a secure context, such as HTTPS or localhost.

Optional casting

Set casting: true in a deck’s frontmatter, or pass casting to Deck or Presentation, to expose Cast to a receiver when the browser provides the Presentation API. The receiver loads the same public deck URL and follows slide/step/blackout state. This is experimental and requires a compatible receiver selected by the browser. A supported browser alone does not establish device compatibility. Stop casting ends a connected presentation; cancelling or losing a receiver keeps the local view usable.

Local highlights and comments

Select text and use Annotations to save a highlight or comment in your browser. The Annotations component also works independently in an article. Export/import uses a bounded W3C Web Annotation JSON profile. These reader notes are separate from authored speaker notes and are not broadcast to other screens.

Ready for the room is a rehearsal deck for these controls.