📖 Introduction

What is Narro, and should I be writing markdown or React?

2 min readView as markdown

Narro builds presentations out of web technology. A deck is either a markdown file or a tree of React components; either way it renders in a browser, lives in Git, and exports to PPTX, PDF, or a single self-contained HTML file.

Two ways to write a deck

Both modes use the same runtime, the same navigation, and the same export pipeline. Pick by how much control you want, not by how big the deck is — markdown decks can drop into React wherever they need to.

Markdown mode

One .md file, no project to scaffold:

npx @getnarro/cli new deck.md
npx @getnarro/cli dev deck.md

The dialect is designed as a ladder with no cliff: plain markdown → layout directives → per-element Tailwind → your own React layouts → full MDX with live components. You climb it without ever rewriting the deck. See Markdown mode.

React mode

A Vite project where every slide is a component:

npm create narro@latest my-deck

Reach for this when slides need real application logic — live data, custom interaction, a component you already have. See First deck.

Why not PowerPoint

Narro is worth the setup when you need something a WYSIWYG tool cannot give you:

  • Code that is really code — a fence in your deck is the same text your editor lints, syntax highlighted at build time, and live components if you want them running on the slide
  • Version control — a deck is text, so it diffs and merges
  • Reuse — a slide is a component; a component works in the next deck too
  • Generation — text in, deck out, which is what makes AI authoring practical

If your deck is five bullet points and a photo, use PowerPoint. Narro is for the cases where you have been fighting the tool.

Packages

PackageWhat it is
@getnarro/cliCLI tools for creating and managing Narro presentations
@getnarro/coreThe React runtime for Narro presentations — Presentation, Slide, navigation, transitions, and speaker notes
@getnarro/docsNarro’s documentation as data — markdown pages, a generated component API reference, and llms.txt
@getnarro/markdownMarkdown & MDX authoring for Narro presentations
@getnarro/marketplaceThemes, colour schemes, and templates for Narro presentations
@getnarro/mcp-serverMCP (Model Context Protocol) server for AI-assisted Narro presentation creation
@getnarro/shared-uiSlide components for Narro presentations — headings, text, lists, code, media, charts, and layouts
create-narroScaffold a new Narro presentation

The npm package named narro is unrelated to this project. Everything here is under the @getnarro/ scope. The binary called narro comes from @getnarro/cli.

IntroductionWhat is Narro, and should I be writing markdown or React?
InstallationWhat do I install, and what does the project look like afterwards?
First DeckWhat does a working React deck look like, end to end?
Markdown ModeHow do I split a slide, style one word, or reveal a line — without leaving the markdown file?
Writing AI PromptsWhat do I tell an AI so the deck it writes actually builds?
Rules for AI AgentsWhat do I paste into my repo so an agent stops writing decks that build wrong?
React APIWhich component or hook do I import, and what does it take?
CLIWhich command do I run, and what are its flags?
Markdown APIHow do I read, edit, or validate a deck file from my own code instead of by hand?
Component ReferenceWhat props does this component take, and which package do I import it from?
Verifying a deckHow do I know my deck is actually correct?
AnimationHow do I reveal a list one line at a time, or move between slides with something other than a cut?
NavigationHow does the audience move through the deck, and how do I present it?
Canvas & PositioningHow do I put something at an exact position instead of in the flow?
Images & MediaHow do I use an image as a background, tint it, or embed a video?
ArchitectureWhich package owns what, and why is the seam where it is?
Transform ModeHow do I zoom and pan across one big canvas instead of cutting between slides?
Import & ExportHow do I get this deck out as PPTX, PDF, or one file I can email?
AI IntegrationHow do I wire an AI assistant up to Narro so it can write and build decks?
ThemingHow do I change the colours, fonts, and overall look of a deck?
Deck TemplatesHow do I define one house style with named layouts my slides can reference, like a PowerPoint master?
TroubleshootingSomething is wrong with my deck. What is it, and how do I fix it?
LimitationsWhat can't Narro do, and what do I do instead?