# Narro

> Developer-first presentations. Author decks in Markdown or React, render them
> in the browser, export to PPTX, PDF, or a single HTML file.

Narro is text, so you can write a deck directly. This file plus the linked
resources are enough — you do not need to have seen the repository.

## Read this first

- **Everything in ONE file (no follow-up fetches — take this if you can only fetch once):** https://getnarro.com/llms-full.txt
- **No web access?** The same documentation ships through npm, over the registry
  that already installed your packages: `npm i -D @getnarro/docs`, then read
  `@getnarro/docs/llms-full.txt`, `@getnarro/docs/catalog.json`, or
  `@getnarro/docs/content/<slug>.md`. It pins to the version actually installed.
- **Rules to paste into your own AGENTS.md / CLAUDE.md / .cursor/rules:** https://getnarro.com/docs/agent-rules.md
- **Then check your work** — this is the part that matters more than the prose:

      npx @getnarro/cli check deck.md --render    # what every slide renders: elements, classes, text
      npx @getnarro/cli check deck.md --strict    # the CI gate: warnings are errors
      npx @getnarro/cli check deck.md --fit       # does the content fit the slide? (needs a browser)
      npx @getnarro/cli build deck.md             # the real build

  `check` names the bad layout, the unknown theme, the malformed directive, and
  every class that was written but landed on nothing. A deck you have not run it
  on is a deck you have not verified. `--strict` is the CI gate; `--render`
  answers "did that class attach to the word or the paragraph?" without a browser;
  `--fit` is the only check that can tell you a dense slide is clipping, and the
  only narro-provided check React mode has (point it at `dist/`).

## Fastest path to a deck

    npx @getnarro/cli new deck.md     # a single-file markdown deck
    npx @getnarro/cli dev deck.md     # open it, hot-reloading

Or scaffold a React project:

    npm create narro@latest my-deck

Note: the npm package named `narro` is unrelated to this project. Narro's
packages are all under the `@getnarro/` scope, and the CLI binary `narro`
comes from `@getnarro/cli`.

## Which mode

| You want | Use | Start at |
| --- | --- | --- |
| One file, no build setup, deck is prose-shaped | Markdown mode | https://getnarro.com/docs/markdown-mode.md |
| Live components, data, custom interaction | React mode | https://getnarro.com/docs/react-api.md |

You do not have to choose permanently: markdown decks climb to per-element
Tailwind, then to ejected React layouts, then to MDX, without being rewritten.

## Closed sets — do not invent names

Every value below is generated from the shipping source. If a name is not in
this list it does not exist, and a deck naming it will build and render wrong
rather than fail loudly. The full machine-readable set, including every
component's props and every exported string union, is one fetch:

- https://getnarro.com/catalog.json
- https://getnarro.com/components.json — every component's props, read out of the TypeScript types
- https://getnarro.com/llms/<Component>.md — one component's reference, on its own URL (names are
  case-sensitive and exact: https://getnarro.com/llms/Presentation.md). https://getnarro.com/llms/index.md lists
  every valid name; a guessed name 404s, so look it up rather than retrying.
- https://getnarro.com/schema/deck-frontmatter.schema.json
- https://getnarro.com/schema/slide-frontmatter.schema.json

Built-in layouts (`layout:` in slide frontmatter): default, cover, section, quote, end, two-column, three-column, image-right, image-full

Themes (`theme:` in deck frontmatter): default, corporate-dark, minimalist-light, creative-gradient, ocean-blue, forest-green, sunset-warm, midnight-purple, tech-dark, startup-bold, academic-classic

Colour schemes — **not a frontmatter key.** They are palettes, applied with
`narro themes apply <id> --color-scheme` or read as data from
`@getnarro/marketplace` (`getColorSchemeById`): ocean-blue, sunset-warm, forest-mist, royal-purple, rose-gold, arctic-blue, charcoal-slate, emerald-night

Font presets — **not a frontmatter key.** Applied from React with
`applyFontPreset(name)` from `@getnarro/core`: system, inter, roboto, openSans, lato, montserrat, poppins, raleway, sourceSerif, playfairDisplay, merriweather, jetBrainsMono

Deck frontmatter keys: title, author, date, theme, template, aspectRatio, transition, class, keyboard, mouse, touch, routing, favicon, maxDuration, plus any key beginning
`x-` — those are yours, nothing reads them, and `check --strict` stays quiet.

Slide frontmatter keys: layout, class, id, transition, background, notes

Tailwind in `{ … }`: whatever Tailwind calls it, including arbitrary values
(`text-[10px]`, `bg-[#0a0a0a]`), opacity modifiers and fractions
(`bg-white/5`, `w-1/2`), variants (`hover:`, `md:`, `dark:`), half-steps
(`p-1.5`) and `!` overrides. The one exception is a literal `{` or `}` inside
the block — put that class in `deck.css`.

Templates for `npm create narro@latest`: markdown-minimal, markdown-app, markdown-docs, minimal, corporate, developer, creative, bold-statement, visual-story, data-narrative, startup-pitch, tech-conference, template0

Components (80 total; props at https://getnarro.com/components.json):
AnimatePresence, Canvas, CanvasElement, CanvasShape, ErrorBoundary, ErrorOverlay, MarqueeRow, MasonryBackground, Motion, MotionContainer, MotionList, MotionNumber, MotionPresence, MotionSpotlight, MotionStep, MotionSteps, MotionText, MotionTransform, NebulaBackground, Notes, OverviewGrid, Presentation, PresenterNotes, Slide, SlideContent, TransformSlide, TrustedByMarquee, AgendaItem, AnimatedList, Animation, Badge, BigText, Callout, Card, Chart, Code, CommentForm, CommentItem, CommentMarker, CommentPanel, ContentSlide, CountingNumber, Diagram, DottedArc, DualColumnTextAndImage, Embed, FlowDiagram, FourColumn, Fragment, Grid, Heading, HexPatternBackground, Icon, Image, ImageBackground, ImageSlide, ImageSpotlight, InfoCardWithIcon, List, LogoGrid, MorphElement, ProcessFlowChart, ProfileCard, ProgressRing, Quote, ScrollableImage, Text, ThreeColumn, TimelineWithIndicators, TitleSlide, TitleSlideWithElement, TwoColumn, TwoColumnHighlight, TypewriterText, Video, WaveLine, WordReveal, Workflow, WorkflowStep, ZoomImage

## Documentation

Every page below is also available as markdown by appending `.md` to its URL —
same content, a fraction of the tokens, no markup to parse back out.

### Start here

- [Introduction](https://getnarro.com/docs/introduction.md): What is Narro, and should I be writing markdown or React?
- [Installation](https://getnarro.com/docs/installation.md): What do I install, and what does the project look like afterwards?
- [First Deck](https://getnarro.com/docs/first-deck.md): What does a working React deck look like, end to end?
- [Markdown Mode](https://getnarro.com/docs/markdown-mode.md): How do I split a slide, style one word, or reveal a line — without leaving the markdown file?
- [Writing AI Prompts](https://getnarro.com/docs/ai-prompts.md): What do I tell an AI so the deck it writes actually builds?
- [Rules for AI Agents](https://getnarro.com/docs/agent-rules.md): What do I paste into my repo so an agent stops writing decks that build wrong?

### Reference

- [React API](https://getnarro.com/docs/react-api.md): Which component or hook do I import, and what does it take?
- [CLI](https://getnarro.com/docs/cli.md): Which command do I run, and what are its flags?
- [Markdown API](https://getnarro.com/docs/markdown-api.md): How do I read, edit, or validate a deck file from my own code instead of by hand?
- [Component Reference](https://getnarro.com/docs/components.md): What props does this component take, and which package do I import it from?

### Guides

- [Animation](https://getnarro.com/docs/animation.md): How do I reveal a list one line at a time, or move between slides with something other than a cut?
- [Navigation](https://getnarro.com/docs/navigation.md): How does the audience move through the deck, and how do I present it?
- [Canvas & Positioning](https://getnarro.com/docs/canvas-positioning.md): How do I put something at an exact position instead of in the flow?
- [Images & Media](https://getnarro.com/docs/media.md): How do I use an image as a background, tint it, or embed a video?
- [Architecture](https://getnarro.com/docs/architecture.md): Which package owns what, and why is the seam where it is?
- [Transform Mode](https://getnarro.com/docs/transform-mode.md): How do I zoom and pan across one big canvas instead of cutting between slides?
- [Import & Export](https://getnarro.com/docs/import-export.md): How do I get this deck out as PPTX, PDF, or one file I can email?
- [AI Integration](https://getnarro.com/docs/ai-integration.md): How do I wire an AI assistant up to Narro so it can write and build decks?
- [Theming](https://getnarro.com/docs/theming.md): How do I change the colours, fonts, and overall look of a deck?
- [Deck Templates](https://getnarro.com/docs/deck-templates.md): How do I define one house style with named layouts my slides can reference, like a PowerPoint master?
- [Troubleshooting](https://getnarro.com/docs/troubleshooting.md): Something is wrong with my deck. What is it, and how do I fix it?
- [Limitations](https://getnarro.com/docs/limitations.md): What can't Narro do, and what do I do instead?