recit.config

recit.config.ts is the only configuration file of a Récit project. A deck project puts its sections there. A site adds its site options at the same level (see A site). recit dev and recit build read the same file as the site, so a deck looks the same in both.

Supported formats: .ts, .tsx, .mts, .js, .jsx, .mjs, .json, or --config <file> on the command line. The CLI looks for it next to the deck, then in each parent directory up to the project root. A site only loads .ts, .tsx, .js, .jsx and .mjs.

recit.config.ts
import { defineConfig } from "recit/config"; // or "@recit/core/config"

export default defineConfig({
  metadata: { title: "Lorem ipsum", author: "Dolor Sit", lang: "en" },
  deck: { aspectRatio: "16:9", transition: "slide" },
  theme: {
    defaultMode: "dark",
    colors: { primary: "#7c3aed", accent: "#2563eb" },
    dark: { primary: "#a78bfa" },
    radius: "24px",
    fonts: { heading: "Georgia, serif" },
    customCss: "./styles.css",
  },
  footer: {
    left: "{title}",
    center: "{author}",
    right: "{slide} / {total}",
    logo: "./logo.svg",
    hideOn: ["cover", "image"],
  },
  components: "./components/index.tsx",
  rules: { maxBulletPoints: 6, maxWordCount: 40, enforceAntiOverload: false },
  syntaxHighlighting: { themes: { light: "github-light", dark: "github-dark" } },
  mermaid: { securityLevel: "strict" },
  security: { allowHtml: false },
  deck: { transition: "fade" },
});

Key	Description	Details
`metadata`	`title`, `author`, `description`, `lang` (interface language)	—
`theme`	named theme, colors, dark palette, radius, fonts, default mode, custom CSS	Theme
`footer`	three zones with variables, logo, hidden layouts	Footer
`components`	module of React components for MDX and `:::component`	MDX
`rules`	density limits	Density rules
`syntaxHighlighting`	Shiki themes and languages	Code, math & diagrams
`mermaid.securityLevel`	`strict` (default), `antiscript`, `loose`	Code, math & diagrams
`security.allowHtml`	raw HTML in a `.md`: sanitized by default (`false`), kept with `true`. An `.mdx` is never sanitized: MDX is code	—
`deck`	`aspectRatio` (`16:9`, `4:3`), `transition`, `designWidth`, `designHeight`, `presenter`	Deck
`motion`	`theme`, `wordsPerSecond`, `aspect` (`16:9`, `1:1`, `9:16`)	Motion
`publish`	stories published by a site: `dir`, `routePrefix`, `entries`, `layout`, `components`	A site
`app`	desktop and mobile application: `productName`, `identifier`, `version`, `icon`, `window`, `allowedOrigins`, `deepLink`, `android`, `ios`, `updater`	Desktop and mobile
`stories`	settings of the stories format (planned). The site keys (`dir`, `routePrefix`…) are rejected here: they belong in `publish`	—
`i18n`	optional languages: `locales`, `defaultLocale`, `fallback`, `strict` (translation warnings become errors), `routing` (`prefix-except-default` or `prefix-always`), `ui` (interface string packs, not read yet)	Languages

Every section is optional. Without a section, the defaults apply.

Validation

defineConfig validates the file and lists every issue with its path:

Code
Invalid recit config (recit.config.ts):
  - theme.colors.primary: expected string, received number
  - deck.transition: expected one of "fade", "slide", "none", received "zoom"

Unknown keys are ignored.

A site

A site keeps its options (site, navigation, redirects, docs…) in the same file. defineConfig from recit/config takes the Récit sections out, since the site framework drops the keys it does not know, and adds the site plugin and the Vite plugin of @recit/site-stories on its own. No other config file and no vite.config.ts are needed.

recit.config.ts
import "@recit/site-stories/styles.css";
import { defineConfig } from "recit/config";

export default defineConfig({
  // Site options
  site: { title: "Lorem Ipsum Docs" },
  navigation: [{ type: "doc", file: "index" }],
  // Récit sections
  publish: { dir: "./stories", routePrefix: "/stories" },
  footer: { left: "{title}", right: "{slide} / {total}" },
});

In a site, metadata, site, theme and syntaxHighlighting are site options. The other Récit sections (footer, rules, deck…) apply to every story, beneath the recit.config.* found next to the story, which also gives the story its theme.

Former names

presentation.config.* still loads, with a warning asking to rename it to recit.config.*. presentation.config.* is read until 0.2.

The configuration of the showcase deck, as an example:

import { defineConfig } from "@recit/core";

export default defineConfig({
  metadata: {
    title: "Showcase",
    author: "Lorem Ipsum Team",
    lang: "en",
  },
  theme: {
    colors: { primary: "#7c3aed", accent: "#2563eb" },
    dark: { primary: "#a78bfa" },
    radius: "24px",
    fonts: { heading: "Georgia, serif" },
    defaultMode: "dark",
    customCss: "./styles.css",
  },
  footer: {
    left: "{title}",
    center: "{author}",
    right: "{slide} / {total}",
    logo: "./logo.svg",
    hideOn: ["cover", "image"],
  },
  components: "./components/index.tsx",
  rules: { maxBulletPoints: 6 },
  // Multilingual: slides.fr.md is the French variant of slides.md
  // (`recit build slides.md --locale fr`, `recit i18n check`)
  i18n: { locales: ["en", "fr"] },
});