@getnarro/markdown

Markdown & MDX authoring for Narro presentations

getnarro.com · Documentation · Ecosystem

The big idea is a customization ladder with no cliff: start in plain markdown and climb — per-slide layout, per-element Tailwind, ejectable React layouts, full MDX with live components — without ever rewriting your deck, and (short of reusable component code) without leaving the single .md file.

narro new deck.md      # scaffold a starter deck
narro dev deck.md      # open it in the browser (hot reload)
narro build deck.md    # static build

The customization ladder

| Rung | You write | Lives in | | --- | --- | --- | | 1. Plain markdown | # Heading, lists, tables… | the .md file | | 2. Directives | layout:, class:, theme: in frontmatter | the .md file | | 3. Tailwind utilities | {.text-8xl .text-brand-500} on any element | the .md file | | 4. Ejected layouts | a React component in layouts/ | beside the file | | 5. Full MDX | import + <LiveComponent/> | file + components |

Dialect reference

Slides & frontmatter

Slides are separated by a line of exactly ---. The file may open with a YAML deck frontmatter block, and each slide may start with its own YAML block.

---
title: Q3 Review          # deck frontmatter
theme: default
aspectRatio: "16:9"
class: font-sans          # default classes on every slide
---

# First slide

---
layout: two-column        # per-slide frontmatter
class: bg-slate-950
id: revenue               # stable id (routing + AI diffing)
---

## Left

::right::

## Right

--- inside fenced code blocks never splits a slide. A YAML block is only treated as slide frontmatter when every line looks like YAML (so a heading or prose is never swallowed).

Deck keys: title, author, date, theme, template, aspectRatio, transition, class, keyboard, mouse, touch, routing, favicon, maxDuration. Slide keys: layout, class, id, transition, background, notes (plus any extra keys, forwarded to the layout as props).

Both are also published as JSON Schema — @getnarro/markdown/schema/*.json, and at https://getnarro.com/schema/deck-frontmatter.schema.json — generated from the same zod objects the parser validates against.

Tailwind attribute syntax (rung 3)

Attach classes, an id, or props to the preceding element with a trailing { … }:

# Big title {.text-8xl .font-black .text-brand-400}

A subtitle. {.text-2xl .opacity-70}

![diagram](./arch.png){.rounded-xl width=800}

• {.foo} → class, {#foo} → id, {key=value} → prop/attribute.
• A block-level attribute line for a list/table must be its own paragraph (blank line above): the attributes attach to the block before it.
• Real MDX expressions ({count}) are left untouched.

Layout slots

::name:: on its own line starts a named slot; content before the first marker is the default slot. Slots are passed to the layout component as props.

Speaker notes

<!-- notes: What to say on this slide. -->

Rendered via the core presenter view (or use the notes: frontmatter key).

Fragments

- appears first {.step}
- appears second {.step delay=200}

MDX (rungs 4–5)

Put import/export statements in the preamble — above the first ---, after the deck frontmatter. They are shared by every slide. Imports inside a slide body are a compile error.

import { LiveChart } from './components/chart'

export const Stat = ({ n, label }) => (
  <div className="text-8xl font-black">{n}<span className="text-2xl">{label}</span></div>
)

---

# Revenue

<LiveChart data={[1, 4, 9]} />
<Stat n="42%" label="growth" />

Layouts

Reference a layout by name in slide frontmatter (layout: two-column). A name resolves in order:

1. <deckDir>/layouts/<name>.{tsx,jsx,mdx} — your own, shadows everything.
2. The deck template's layouts.
3. The active theme's layouts.
4. The built-ins: default, cover, section, quote, end, two-column, three-column, image-right, image-full.

A layout is a plain React component:

import type { SlideLayoutProps } from "@getnarro/markdown/runtime";

export default function TwoColumn({ children, right }: SlideLayoutProps) {
  return (
    <div className="grid h-full grid-cols-2 gap-12 p-16">
      <div>{children}</div>
      <div>{right}</div>
    </div>
  );
}

Deck templates

One file beside the deck — the slide master — holds the design tokens, the chrome every slide carries, and a set of layouts addressed by the id a slide names:

// deck.template.ts
import type { DeckTemplate } from "@getnarro/markdown";

export default {
  id: "acme",
  tokens: { colors: { brand: "#5b8cff" } },
  master: { footer: { text: "{title} · {date}" }, slideNumber: { from: 2 } },
  layouts: { "title-slide": { base: "cover", master: false } },
} satisfies DeckTemplate;

It is data, so narro check resolves every id, slot and token in it without a browser. See deck templates.

Single-file decks

Rungs 1–3 (and inline MDX component definitions) live entirely in one .md file — email it, commit it, hand it to an LLM. Ejected layouts and imported components live beside the file and are referenced by name; a deck becomes a folder (deck.md + layouts/ + components/) only when you opt into code.

Programmatic API

import { splitDeck, compileDeck } from "@getnarro/markdown";
import { narroMarkdown } from "@getnarro/markdown/vite";

• @getnarro/markdown — splitDeck, compileDeck, frontmatter parsing, deck templates (resolveDeckTemplate, validateTemplate, applyTemplateToSlide).
• @getnarro/markdown/vite — the Vite plugin.
• @getnarro/markdown/runtime — DeckShell, DeckSlide, SlideLayoutProps.
• @getnarro/markdown/layouts — the built-in layout registry.

The Narro ecosystem

| Package | What it is | | --- | --- | | @getnarro/cli | CLI tools for creating and managing Narro presentations | | @getnarro/core | The React runtime for Narro presentations — Presentation, Slide, navigation, transitions, and speaker notes | | @getnarro/docs | Narro's documentation as data — markdown pages, a generated component API reference, and llms.txt | | @getnarro/markdown | Markdown & MDX authoring for Narro presentations ← you are here | | @getnarro/marketplace | Themes, colour schemes, and templates for Narro presentations | | @getnarro/mcp-server | MCP (Model Context Protocol) server for AI-assisted Narro presentation creation | | @getnarro/shared-ui | Slide components for Narro presentations — headings, text, lists, code, media, charts, and layouts | | create-narro | Scaffold a new Narro presentation |

All eight ship from one repository and release together.

The npm package named narro is unrelated to this project. Narro's packages are all under the @getnarro/ scope; the CLI binary narro comes from @getnarro/cli.

Website · Documentation · llms.txt · GitHub · Issues · Changelog

Released under the MIT License.