Configuration reference
Every field a site accepts in refrakt.config.json, grouped by what it does.
This page is generated from refrakt.config.schema.json — the same schema your editor validates against — so it lists what the code actually accepts rather than what someone remembered to write down. For how the file is shaped (single-site, multi-site, path resolution), see Sites.
Fields marked theme-defaultable can also be supplied by a theme's manifest. The site config wins; the theme is the fallback.
Content and theme
What the site is built from.
contentDir
string · required
Path to the content directory, relative to the project root. Required for a site to load.
theme
string | SiteThemeConfig · required
Active theme — accepts a package name string (legacy shorthand) or a full SiteThemeConfig with presets, token overrides, mode overlays, and code-block colour scheme.
target
string
Documentation-only adapter hint (svelte, astro, next, nuxt, eleventy, html). No adapter validates or reads this field today; it serves as an in-config record of the intended adapter. Slated for removal in v1.0.
Site identity
Used for canonical links, social cards and structured data. Every field here is theme-defaultable.
baseUrl
string
Public base URL of the site, used for canonical links, `og:url` and `og:image`.
siteName
string
Human-readable site name, used for `og:site_name` and Organization JSON-LD.
logo
string
Site logo path used in Organization JSON-LD (e.g. `/favicon-192.png`).
defaultImage
string
Default `og:image` for pages that do not set their own. 1200×630 is recommended.
Routing and entities
How pages map to layouts, and which of them become registry entities.
routeRules
RouteRule[]
Route-to-layout mapping rules, evaluated in order — first match wins. A rule may also set `entity`, registering matching pages as registry entities of that type (e.g. `runes/**` → `rune`) without per-page frontmatter.
entityRoutes
EntityRoute[]
Declarative entity → page routes. Each rule generates one page per registered entity matching `type` plus an optional `filter` — the built-in alternative to writing a `contributePages` pipeline hook by hand.
Runes and plugins
Which runes exist, and which package wins when names collide. See Plugins for the conflict-resolution knobs in full.
plugins
string[]
Plugins to merge into this site's ThemeConfig (runes, layouts, hooks, etc.).
runes
RunesConfig
Rune resolution — which package wins when several define the same rune name, extra tag names for existing runes, and runes loaded from local files.
overrides
Record<string, string>
Component overrides, mapping a `typeof` name to a component path relative to the project root.
Presentation
Cross-cutting visual configuration.
icons
Record<string, string>
Custom icon SVGs, merged into the theme's global icon group and referenced by name.
tints
Record<string, object>
Project-level tint presets, available to any page or rune via the `tint` attribute.
backgrounds
Record<string, object>
Named bg presets (keyed by name). Each is a BgPresetDefinition: `style` and/or token-driven `gradient` (engine-resolved), `extends` a base preset, and/or `sandbox` ({ src, framework?, dependencies? }) for a live sandbox backdrop resolved at transform time (SPEC-104). `sandbox` presets are project-level content.
highlight
HighlightConfig
Legacy syntax-highlighting configuration — picks a Shiki built-in theme by name (or a `{ light, dark }` pair) for fenced code blocks. The recommended modern approach is `theme.presets` (which contribute `--rf-syntax-*` token overrides via Lumina syntax presets like `@refrakt-md/lumina/presets/nord`) plus `theme.code.colorScheme` for forced light/dark code blocks. Kept for back-compat; both mechanisms can coexist.
sandbox
SandboxConfig
Sandbox configuration — the runtime program-source directory scanned at build time (SPEC-104, ADR-022).
search
boolean
Whether to render the site-wide search UI (header button + Cmd/Ctrl+K dialog, powered by Pagefind). Defaults to true. Set false to omit the search chrome entirely. Results require a Pagefind index built and served at /pagefind/ — see the Setting up search guide.
Content sources
Where source links resolve from.
repoUrl
string
Canonical GitHub (or compatible) repository URL — e.g. `https://github.com/owner/repo`. Used by the `file-ref` rune (SPEC-078) to build deep-link `View source on GitHub →` URLs of the form `{repoUrl}/blob/{repoBranch}/{path}#L{start}-L{end}`. When absent, `file-ref` falls back to a no-href link / in-page anchor with a build warning.
repoBranch
string
Git ref appended to GitHub source URLs — accepts any branch name, tag, or commit SHA. Defaults to `main` when omitted. Use a commit SHA for archival URLs that won't drift when the file is edited later.
Internationalisation
Locale selection and string overrides — see i18n for the resolution order.
locale
string
Active locale (BCP 47, e.g. `de`). Selects first-party and plugin translation bundles for framework-generated UI text and drives locale-aware date/number formatting. Defaults to `en`.
strings
Record<string, string | Record<string, string>>
Site-level translation overrides for framework-generated UI text, keyed by the auto-derived i18n key (`{scope}.{block}.{ref}`). Highest precedence — these win over first-party and plugin bundles. Each value is a string, or a map of CLDR plural categories (`one`, `other`, …) to strings.
Top-level
Fields that sit outside a site entry, at the root of the file. Everything else above belongs inside site (or an entry under sites).
plan
PlanConfig
Plan-management configuration.
xrefs
XrefPattern[]
Cross-reference URL templates. Patterns are tried in array order when an xref's ID isn't found in the registry (or when the registry-found entity has no usable `sourceUrl`). First match wins.
fileRoots
Record<string, string>
Named file roots — directories that file-reading runes can reach via a `namespace:filename` syntax (e.g. `{% partial file="shared:footer.md" /%}`). Keys are namespace names; values are paths relative to the project root and must point at existing directories. The namespace `site` is reserved.
Keeping this page honest
The rows above come from site/content/_data/config-fields.json, generated by scripts/generate-config-reference.mjs from the schema. A colocated test fails when the artifact is stale, when a schema field has no group, or when a group entry names a field that no longer exists — so a field added to the config cannot quietly go undocumented.
Regenerate with:
npm run config:reference