`, which is the rule in the paragraph above and worth reading twice. Run
`check --render` if you are unsure which one you got.
**In a table, it styles the cell** — `| Total {.text-right .font-black} |` puts
the classes on that `| ` or ` | `.
Repeated blocks on one element merge: classes concatenate, and a later `#id` or
`key=value` wins.
One thing the syntax cannot do: style an *empty* element. `** **{.w-8}`
does not parse, because emphasis needs non-space content.
For a coloured rectangle, a bar, or a spacer, use an **empty container** — it
takes attributes like any other and needs nothing but markdown:
```markdown
:::{.h-2 .w-48 .rounded-full .bg-cyan-400}
:::
```
An inline `` works too and is the shorter answer inside a
sentence — see [MDX](#mdx) below.
### On a fenced code block
An attribute block in the info string styles the ``; the `language-*` class
on the inner `` is left alone, so highlighting still works.
````markdown
```bash {.rounded-xl .bg-black .p-8}
npx @getnarro/cli dev deck.md
```
````
The separate-paragraph form works too, and is the one to use when the fence
already carries other metadata.
## Grouping blocks
`:::` opens a container and a bare `:::` closes it. It takes the same attribute
syntax as any element, and containers nest:
```markdown
:::{.flex .items-center .gap-8}
### 72 KB {.text-6xl .font-black}
Gzipped, including the runtime.
:::
```
This is how you get a row, a grid, or a bordered box without leaving markdown.
Before it existed, every horizontal arrangement had to be a `` carrying
`{.flex .list-none .pl-0}` — two utilities of pure boilerplate to undo list
styling — and anything a list could not express was out of reach.
Every container carries `rs-container`, so a stylesheet can target them.
Three things worth knowing before you build a grid out of these:
- **`:::` must start at column 0.** An indented `:::` is not a container marker;
it stays on the slide as literal text (and `check` reports it).
- **Blank lines inside are optional.** The compact form above and the spaced form
(a blank line after the opening fence and before the closing one) compile
identically, at any nesting depth. Use whichever reads better.
- **There is no iteration.** Twelve cards is twelve containers; a deck cannot
loop, reference-and-repeat, or define a fragment to reuse. A twelve-item grid
is around 120 lines of markdown, and that is the point at which
[MDX](#mdx) and a `.map()` — 15 lines — is the better tool. This is the
sharpest edge of the mode; see
[Limitations](/docs/limitations.md).
## Layout slots
`::name::` on its own line starts a named slot. Content before the first marker
is the `default` slot. Slots arrive at the layout component as props.
```markdown
---
layout: two-column
---
Goes to `children`.
::right::
Goes to the `right` prop.
```
**Every built-in layout takes `::header::` and `::footer::`** — full-width rows
above and below the content, whatever the layout puts in between:
```markdown
---
layout: two-column
---
::header::
## Before and after {.text-5xl}
::default::
The old way.
::right::
The new way.
```
Both rows render only when filled, so a deck that never uses them is unchanged.
Title-above-two-panels is the most common shape a deck asks for, and they were
column-layout-only for long enough that decks on `default` and `cover`
hand-stacked paragraphs to fake a header. An eyebrow line above a cover title, a
source note under a chart, and a page footer are all this.
`::default::` reopens the default slot, which is how you write a header first and
then the main content.
## Speaker notes
```markdown
```
The comment can sit anywhere in the slide, and a slide may carry more than one —
they are concatenated in source order, separated by a blank line. The comments
are removed before compilation, so nothing reaches the slide.
The `notes:` frontmatter key is the alternative, and is the better one when the
text is long enough to want YAML's block scalar:
```markdown
---
notes: |
Open with the customer story.
Then the number.
---
```
Either way the text shows up in the presenter view and nowhere else.
## Fragments
Reveal content step by step with `.step`:
```markdown
- appears first {.step}
- appears second {.step delay=200}
```
`delay` is milliseconds, and it is **consumed** by the step wrapper rather than
forwarded — it will not appear as an attribute on the element.
Each marked node is wrapped at compile time, and reaches the DOM as:
```html
…
```
Those hooks are the supported way to target fragments from a theme or a custom
stylesheet. `.step` is the only reserved class name in the attribute syntax:
every other `{.foo}` is passed through as a literal class.
## Layouts
Reference a layout by name in slide frontmatter. A name resolves in order, first
match winning:
1. `/layouts/.{tsx,jsx,mdx,ts,js}` — yours, shadows everything
2. The [deck template](/docs/deck-templates)'s layouts, if the deck has one
3. The active theme's layouts
4. The built-ins:
| Layout | Slots |
| --- | --- |
| `default` | `header`, `footer` |
| `cover` | `header`, `footer` |
| `section` | `header`, `footer` |
| `quote` | `header`, `footer` |
| `end` | `header`, `footer` |
| `two-column` | `right`, `header`, `footer` |
| `three-column` | `two`, `three`, `header`, `footer` |
| `image-right` | `header`, `footer` |
| `image-full` | `header`, `footer` |
That table is generated from `builtinLayoutSlots`, which is also what the
validator checks against — so a slot name it does not list is one `narro check`
will reject, and content after it would not have rendered.
Two things the table does not show:
**Column names are positional, and `three-column` does not use `right`.** Its
slots are `two` and `three`; `two-column` has one slot called `right`. Writing
`::right::` on a three-column slide puts the content in a slot nothing reads.
**The image layouts take their image from frontmatter, not a slot.**
`image-right` and `image-full` read the slide's `image:` key, falling back to
`background:` — which is why neither has a named slot:
```markdown
---
layout: image-right
image: ./architecture.png
---
## What changed
The old pipeline is on the right.
```
A layout is a plain React component:
```tsx
import type { SlideLayoutProps } from "@getnarro/markdown/runtime";
export default function TwoColumn({ children, right }: SlideLayoutProps) {
return (
);
}
```
### Naming your own layouts without writing components
A [deck template](/docs/deck-templates) is one file beside the deck that defines
layouts as data — a built-in plus classes, defaults, and the chrome every slide
carries — and gives each one an id the markdown references:
```ts
// deck.template.ts
export default {
id: "acme",
master: { footer: { text: "{title} · confidential" } },
layouts: {
"metric-split": { base: "two-column", regions: { right: "text-right text-accent" } },
},
};
```
```markdown
---
layout: metric-split
---
```
It is the slide master: `narro check` knows the ids, the deck stops naming
colours, and rebranding is one file.
## MDX
A slide is MDX, whatever the file is called. Components, JSX and `{expression}`
work in a `.md` deck exactly as they do in a `.mdx` one.
Put `import` and `export` statements in the **preamble**: the statements at the
top of the file, after the deck frontmatter and before the first slide. They are
shared by every slide, and the preamble ends where the statements do — a `---`
after them is allowed but not required. Anything else up there is an error
rather than a slide that quietly disappears. An import inside a slide body is
also an error; move it to the preamble.
Two consequences of slides being MDX, both of which produce a build error
naming the line rather than a surprise on the projector:
- **HTML is JSX.** Every tag closes (`
`, not `
`) and attributes are
camelCased (`className`, not `class`).
- **`{` opens an expression** unless the block is attribute syntax. Write `\{`
for a literal brace, or put the text in `` `inline code` ``.
```markdown
import { LiveChart } from './components/chart'
export const Stat = ({ n, label }) => (
{n}{label}
)
# Revenue
```
## Formatting a deck
Run `narro fmt deck.md`. **Do not point a general markdown formatter at a deck.**
The reason is [the space rule](#which-element-it-attaches-to): `**word**{.red}`
styles the word and `**word** {.red}` styles the block, so any formatter that
reflows a paragraph can move an attribute block onto its own line and silently
change what it applies to. Prettier does exactly that. Nothing errors, `check`
sees a legal deck, and the design is different.
`narro fmt` does only what cannot change rendering: trailing whitespace, runs of
blank lines, `---` separators, YAML colon spacing, and collapsing multiple spaces
before an attribute block — preserving tightness, which is the one thing that
carries meaning. `narro fmt --check` is the CI form.
If your repo runs Prettier over everything, add the deck to `.prettierignore`.
The scaffolded markdown templates already do.
## In a scaffolded project
`markdown-minimal` is the deck and nothing else — `deck.md`, and a
`package.json` that pins the CLI. The `markdown-app` and `markdown-docs`
templates wire the same plugin into a normal Vite project, which is what you
want when the deck needs its own dependencies or pinned versions:
```ts
// vite.config.ts
import path from "node:path";
import { narroMarkdown } from "@getnarro/markdown/vite";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
narroMarkdown({ deckPath: path.resolve(import.meta.dirname, "deck.md") }),
react(),
tailwindcss(),
],
resolve: { dedupe: ["react", "react-dom", "@getnarro/core"] },
});
```
The plugin exposes the compiled deck as `virtual:narro/deck` and its stylesheet
as `virtual:narro/deck.css`. Its full option list — including `strict`, which
promotes validation warnings to errors and belongs in CI — is on the
[markdown API](/docs/markdown-api#the-vite-plugin) page.
## Driving the format from code
Everything on this page is also reachable as a library. `@getnarro/markdown`
parses, edits, validates, and compiles decks, and it is what the CLI and the MCP
server are built on — a deck can be read and rewritten without a regex.
The one distinction worth knowing before you start: `splitDeck` parses for
*rendering* and loses the original YAML text, while `parseDeckDocument` parses
for *editing* and round-trips exactly, so a tool can change one slide without
reformatting the other forty. See [markdown API](/docs/markdown-api).
## One dialect
Narro has exactly one markdown dialect: this one. Older material described a
directive syntax (`::text[…]{size="lg"}`, `:::three-columns`) that was never
part of the shipping pipeline — that implementation has been removed. If you
find those directives in a deck, they will render as literal text. |