Markdown authoring guide

Write your SuperDeck slides in Markdown. This guide shows you how to structure content and use block syntax.

Quick start

A basic slide with a title and content:

---
title: My First Slide
---

@block

# Welcome to SuperDeck

- Write slides in Markdown
- Use blocks to control layout
- Style with Flutter themes

Slide options (front matter)

Each slide can have YAML front matter with these options:

• title – Slide title (appears in navigation and exports)
• style – Named style variant to apply (defined in DeckOptions.styles)
• template – Named template to apply (defined in DeckOptions.templates; 'none' to opt out)
• Custom keys – Access via slide.options.args['keyName'] in slide parts

---
title: Product Vision
style: overview
---

Block types

Use these block types when you compose slides:

• @section for horizontal layout containers.
• @block for markdown content.
• @widget for custom Flutter widgets.

For the full syntax and argument reference, see the Markdown syntax reference.

Layout building blocks

@section

Groups blocks horizontally. Use sections to create multi-column layouts.

@section {
  align: center
  flex: 2
}

@block

Renders markdown content. Most slides use one or more columns.

@block {
  flex: 2
  align: topLeft
}

# Promise, Problem, Proof
- Lead with the outcome
- Contrast with the current state
- Finish with supporting data

Common properties

Use these properties on blocks. Sections support flex and align; scrollable applies to child blocks and widgets.

• flex – Relative size (default: 1). A column with flex: 2 takes twice the space of flex: 1
• align – Content alignment such as topLeft, center, and bottomRight
• scrollable – Enable scrolling for overflow content (default: false)

For complete value definitions, see the Markdown syntax reference.

Built-in widgets

@image

Display images with fit options.

@image {
  src: assets/value-loop.png
  fit: contain
  height: 420
}

For all @image arguments, see the Markdown syntax reference.

@dartpad

Embed interactive DartPad examples.

@dartpad {
  id: "d7b09149b0843f2b9d09e081e3cfd5a3"
  theme: dark
  run: true
}

For all @dartpad arguments, see the Markdown syntax reference.

DartPad uses an embedded WebView. Make sure your target platform supports WebViews.

Custom widgets

Register widgets in DeckOptions.widgets, then use them with the shorthand syntax:

@metricCard {
  label: Activation
  value: "72%"
  trend: up
}

The widget name becomes the block type (@metricCard), and all properties are passed to the registered WidgetFactory as Map<String, Object?>. Your widget (or a helper like MetricCardArgs.parse(args)) decides how to interpret them.

Markdown features

Standard Markdown

Use headings, lists, tables, and code blocks as you normally would:

@block

# Slide Title

- First point
- Second point
- Third point

| Feature | Status |
|---------|--------|
| Auth    | Done   |
| API     | In Progress |

Alerts

Use GitHub-style alerts for callouts:

> [!NOTE]
> Additional context for readers.

> [!WARNING]
> Important information to highlight.

> [!TIP]
> Helpful suggestions.

Hero animations

Add class names to animate elements between slides:

# Roadmap {.hero-title}
![Diagram](assets/roadmap.png) {.hero-visual}

Elements with matching class names animate smoothly during slide transitions.

Styling

Apply named styles to individual slides using front matter:

---
title: Key Takeaways
style: recap
---

Define styles in your app:

DeckOptions(
  styles: {
    'recap': SlideStyle(
      h1: TextStyler().style(TextStyleMix(fontSize: 64)),
    ),
  },
)

See the SuperDeck Overview for more styling options.

Next steps

• Explore syntax details in the Markdown syntax reference
• Explore block behavior in the Block types reference
• Explore build tooling in the CLI Reference
• Create custom widgets with the Custom Widgets Guide