Slides

Basics

Slides are separated by --- and may contain YAML frontmatter:

---
layout: Section
---

# Big Idea

Content here.

Layout names are PascalCase. If no layout: is specified, Default is used.

Layouts receive a title prop extracted from the first # heading in the slide, plus any additional frontmatter fields as props.

Comments

HTML comments are supported anywhere in deck MDX and are removed before compilation, so they never render:

<!-- reminder: shorten this slide -->

# Roadmap

Shipping next quarter. <!-- confirm the date -->

<!--
Multi-line comments work too.
-->

A line that contains only a comment disappears completely, so comments between paragraph lines do not break the paragraph. Comments inside fenced code blocks stay literal and are rendered as code. An unterminated comment hides everything after it in that file.

MDX expression comments ({/* ... */}) keep working as well.

Multiple MDX Files

The deck entry file defaults to deck.mdx, and --deck <file.mdx> can select another root document. Additional MDX files are included via standard ESM imports:

import Intro from './slides/intro.mdx'
import Demo from './slides/demo.mdx'

<Intro />

<Demo />

How Honeydeck Distinguishes MDX from Components

• Imports from .mdx files → slide-structural (creates slide boundaries).
• Imports from .tsx/.ts/.jsx/.js or packages → normal inline components.

import DemoSlides from './demo.mdx'   // slide group
import Chart from './Chart'            // normal inline component

Import Formatting

Imports at the top of the deck are shared with every slide. They may be written on one line or spread across several lines:

import {
  MapIcon,
  RouteIcon,
} from './components/icons'

Import statements written inside fenced code blocks stay literal code text.

Slide Expansion

If an imported .mdx file contains --- separators, those slides are expanded at the location where the component is rendered. Rendering an imported MDX component always creates slide boundaries around it.

Frontmatter in Imported Files

• The first frontmatter block of the deck entry file defines deck-level settings and first-slide settings.
• Frontmatter in imported MDX files is slide-level only — they cannot define deck settings.

Default Layouts

Honeydeck's built-in defaults are clean and minimal. They provide:

Two-Column Layout

Uses explicit slot components:

---
layout: TwoCol
---

import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'

<Left>
## Pros
- Fast
- Simple
</Left>

<Right>
## Cons
- Limited
</Right>

Image Layout

Displays a specified image prominently (not as background):

---
layout: Image
image: /diagrams/architecture.png
darkImage: /diagrams/architecture-dark.png
---

# System Architecture

Caption below the image.

Side Image Layouts

Use ImageLeft or ImageRight when the image should sit beside the slide content:

---
layout: ImageLeft
image: /photos/product.jpg
darkImage: /photos/product-dark.jpg
alt: Product detail
---

# Product Detail

Short supporting copy beside the image.

Custom Components in Titles

The first # heading of a slide is extracted as the title prop passed to layouts. Titles are not limited to plain text — inline Markdown and custom React components are preserved:

import SparkleButton from './SparkleButton'

# Introducing <SparkleButton />

Body content follows the title.

Components used in the title must be imported at the top of the slide. They resolve with the same rules as components used in the body. Inline Markdown emphasis, code, and links work as usual:

# Honeydeck `v1.0` is **here**

Timeline-consuming components such as <Reveal> are not assigned steps when used in a title.

Assets

Static files live in public/ and are served from the web root. Reference them without the public/ prefix:

<img src="/cover.jpg" />