# Scenes

A story is a list of **scenes**. The same file is read as slides by the deck format and as shots by
the motion format: what follows is true of both. What only a deck does lives under
[Formats › Deck](/formats/deck/overview).

## Split the story

A `---` line separates two scenes. It can carry the scene's **attributes**, as `key=value` pairs or
JSON:

```md
--- layout=center transition=fade

# Centered scene

--- { "layout": "grid", "cols": 3, "id": "pillars" }

# Three pillars
```

`id` names a scene, whatever the format. `layout`, `cols` and `transition` above are read by the
deck: see [Slide options](/formats/deck/slide-options). A film reads `type`, `dur` and `hold`
instead — see [Motion](/formats/motion).

:::note

A `---` inside a code block or a `$$` block is **not** a separator, and `----` stays a horizontal
rule.

:::

## Story front matter

The first YAML block holds the story's metadata, and takes precedence over `recit.config.ts`:

```yaml
---
title: Lorem ipsum
author: Dolor Sit
aspectRatio: 16:9      # deck: 16:9 or 4:3; a film also takes 1:1 and 9:16
colorMode: light       # light | dark | system
lang: en               # interface language (en, fr)
description: "Shown in galleries and in the HTML head"
---
```

A format's own settings can sit flat, as above, or under its section — `deck:` for the slides,
`motion:` for the film — so one source can carry both without a name clash. Every key is listed in
[recit.config](/documentation/configuration/recit-config).

## Small inline elements

These directives are the same in every format:

| Syntax                             | Result                                                       |
| ---------------------------------- | ------------------------------------------------------------ |
| `:badge[New]{type=success}`        | badge (`default`, `primary`, `success`, `warning`, `danger`) |
| `:kbd[Ctrl]`                       | keyboard key                                                 |
| `:::callout{type=tip title="Tip"}` | callout (`info`, `tip`, `warning`, `danger`, `note`)         |

Every directive and component is shown with its props on [components.recit.dev](https://components.recit.dev).

<StoryEmbed slug="showcase" slide={1} />