Copy page

Reference

Architecture

Récit keeps a single chain, whatever the output:

Code
Markdown / MDX  ──parse──►  Story (a list of Scenes)  ──render──►  format

A scene is the common unit: a slide in a deck, a shot in a video, a section in a report, a panel in a webtoon, a chapter in a book.

From source to formats

Around the chain, in every format:

• @recit/components: the same Callout, Grid, Code, Mermaid… everywhere
• @recit/theme: tokens and the CSS of each format
• @recit/cli: the recit command — every one of them is on the CLI reference, which this page does not copy

The same compiled HTML is displayed by recit dev, recit build, the HTML export, the PDF and the sites: a deck looks the same everywhere.

The Story model

The compiler produces a Story. Fields specific to a format live under a dedicated key: the core knows no format.

TypeScript
type StoryFormat =
  | "deck"
  | "motion"
  | "docs"
  | "report"
  | "toon"
  | "book"
  | "roadmap"
  | "calendar"
  | "stories";

type Story = {
  version: 1;
  format: StoryFormat; // front matter `format:`, "deck" by default
  meta: { title: string; description?: string; author?: string; lang: string };
  settings: ResolvedConfig; // recit.config.ts + front matter, after mergeConfig
  design: { width: number; height: number; aspectRatio: string };
  themeCss: string;
  scenes: Scene[];
  diagnostics: Diagnostic[];
  summary: { totalDurationMs: number; formattedTotalDuration: string };
};

type Scene = {
  id: string; // explicit `id=`, otherwise s1, s2…
  index: number;
  source: { file: string; line: number; endLine: number }; // for diagnostics
  attrs: Record<string, string>; // separator attributes: layout, cols…
  html: string; // sanitized HTML (deck, docs)
  mdast?: Root; // kept for formats that reinterpret the scene (motion)
  steps: number;
  notesHtml?: string;
  durationMs?: number;
  density: DensityReport;
  accessibility: A11yReport;
};

• The deck uses scene.html, steps and notesHtml.
• The motion format will read scene.mdast and scene.attrs to build its shots.
• MDX components are compiled by the CLI or by Vite, one module per scene (<file>.recit-scene-N.jsx).

Packages

The monorepo is split into groups: foundations (packages/core, theme, components), packages/formats/*, packages/integrations/*, distribution (packages/cli), packages/tools/*, one site per sub-domain in sites/*, and examples/*.

Available

Package	Group	Role
@recit/components	foundations	Default components of Récit (callout, code group, media, diagrams…), the same in every format
@recit/core	foundations	Markdown and MDX parser and compiler of Récit: one source, many formats
@recit/site (private)	foundations	The site framework of Récit: routing, prerendering, search and the MDX shell
@recit/theme	foundations	Design tokens, named themes and stylesheets shared by every Récit format
@recit/deck	formats	Presentation format of Récit: deck, presenter console, remote and runtime
@recit/motion	formats	Motion format of Récit: film schema, ops, timing, animation presets, handover extraction, and the Markdown and JSON sources of a film
@recit/motion-blocks	formats	Animated blocks, UI-scene renderer and themes of the Récit motion format
@recit/motion-render	formats	MP4 and still rendering of Récit motion decks with Remotion
@recit/site-stories	integrations	Publishes Récit stories in a Récit site: pages, embeds, fullscreen and search
@recit/cli	distribution	Command line of Récit: recit dev, build, export, and render for motion stories
recit	distribution	Récit: write once in Markdown, tell it everywhere. Alias of @recit/cli, with defineConfig (recit/config)
@recit/app	tools	Desktop and mobile applications of Récit sites: one Tauri 2 shell around the prerendered site
@recit/mcp	tools	MCP server of Récit: build, validate, edit and render motion decks from an agent
@recit/site-kit (private)	tools	Shared configuration, header, footer and MDX components of the Récit sites

Planned

Package	Phase	Role
@recit/studio (private)	P4	Editor and live preview of Récit stories
create-recit (private)	P5	Create a Récit project: npm create recit
@recit/data (private)	P6	Data loading and charts shared by Récit formats
@recit/paged (private)	P6	Shared pagination and PDF output of the Récit report and book formats
@recit/report (private)	P6	Data report format of Récit: HTML and paginated PDF
@recit/toon (private)	P7	Webtoon format of Récit: vertical strip of panels
@recit/book (private)	P8	Book format of Récit: chapters, PDF and EPUB
@recit/roadmap (private)	P9	Roadmap format of Récit: now / next / later, timeline and kanban
@recit/time (private)	P9	Dates, time zones, recurrences and ICS shared by Récit formats
@recit/calendar (private)	P10	Calendar format of Récit: events, agenda views and ICS
@recit/stories (private)	P11	Web stories format of Récit: full-screen cards

The status of each format is on the formats overview.

The site framework

packages/site (@recit/site) is the site framework: routing, prerendering, Pagefind search and the MDX shell that every site of the project, including this documentation, is built on. It is never published on its own.

Récit still reaches it through its plugin API, @recit/site-stories, because a plugin is easier to test and to move than a patch. See the integration.

One configuration file

Each project has a single recit.config.ts, read by the sites, the CLI and the Vite plugin:

• the framework's config loader looks for recit.config.*;
• defineConfig (recit/config, @recit/core/config) validates the Récit sections with zod 4, takes them out of the framework's options and attaches them to the result;
• @recit/site-stories then adds recitPlugin to plugins. Its transformConfig hook lists the package's vite.config.mjs in __pluginDirs, which the framework merges into the site's Vite config: that is how recitVitePlugin is added without a vite.config.ts;
• recit dev | build load the same file and keep only its Récit sections.