# 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](#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`.

```ts title="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](/theme/overview)                                           |
| `footer`                | three zones with variables, logo, hidden layouts                                                                                                                                                               | [Footer](/theme/footer)                                            |
| `components`            | module of React components for MDX and `:::component`                                                                                                                                                          | [MDX](/documentation/writing/mdx)                                  |
| `rules`                 | density limits                                                                                                                                                                                                 | [Density rules](/formats/deck/density-rules)                       |
| `syntaxHighlighting`    | Shiki themes and languages                                                                                                                                                                                     | [Code, math & diagrams](/documentation/writing/code-math-diagrams) |
| `mermaid.securityLevel` | `strict` (default), `antiscript`, `loose`                                                                                                                                                                      | [Code, math & diagrams](/documentation/writing/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](/formats/deck/overview)                                     |
| `motion`                | `theme`, `wordsPerSecond`, `aspect` (`16:9`, `1:1`, `9:16`)                                                                                                                                                    | [Motion](/formats/motion)                                          |
| `publish`               | stories published by a site: `dir`, `routePrefix`, `entries`, `layout`, `components`                                                                                                                           | [A site](#a-site)                                                  |
| `app`                   | desktop and mobile application: `productName`, `identifier`, `version`, `icon`, `window`, `allowedOrigins`, `deepLink`, `android`, `ios`, `updater`                                                            | [Desktop and mobile](/documentation/configuration/app)             |
| `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](/documentation/integrations/site-stories#languages)    |

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

## Validation

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

```text
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`](/documentation/integrations/site-stories) on its own. No other config file
and no `vite.config.ts` are needed.

```ts title="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:

<SourceFile deck="showcase" part="config" title="examples/deck-showcase/recit.config.ts" language="ts" />