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
---

@column

# 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)
• 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.
• @column 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
}

@column

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

@column {
  flex: 2
  align: top_left
}

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

Common properties

Use these properties on blocks:

• flex – Relative size (default: 1). A column with flex: 2 takes twice the space of flex: 1
• align – Content alignment such as top_left, center, and bottom_right
• 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 your widget's parse() method.

Markdown features

Standard Markdown

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

@column

# 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.

Mermaid diagrams

Add Mermaid diagrams using fenced code blocks:

```mermaid
graph TD
  Start --> Plan --> Build --> Ship
```

The CLI renders diagrams to images during build. Run superdeck build after editing diagrams.

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
• Learn about publishing with the CLI Reference
• Create custom widgets with the Custom Widgets Guide