File-ref

/** Per-site configuration. A project may declare a single site (via `site`) or
 *  multiple named sites (via `sites: { name: SiteConfig }`).
 *  Only `contentDir` and `theme` are strictly required for the site to load. */
export interface SiteConfig {
	/** Path to content directory, relative to project root */
	contentDir: string;
	/** Active theme — accepts either a package name string (legacy shorthand)
	 *  or a full {@link SiteThemeConfig} with presets, token overrides, mode
	 *  overlays, and `colorScheme`. */
	theme: string | SiteThemeConfig;
	/** Documentation-only adapter hint (`svelte`, `astro`, `next`, `nuxt`, `eleventy`, `html`).
	 *  No adapter reads or validates this field today; it serves as an in-config record of
	 *  which adapter the site is intended for. Slated for removal in v1.0. */
	target?: string;
	/** Component overrides — maps typeof names to relative paths of replacement components */
	overrides?: Record<string, string>;
	/** Route-to-layout mapping rules, evaluated in order (first match wins) */
	routeRules?: RouteRule[];
	/** Declarative entity → page routes (SPEC-069). Each rule generates one page
	 *  per registered entity matching `type` + optional `filter`. */
	entityRoutes?: EntityRoute[];
	/** Whether to render the site-wide search UI — the header search button
	 *  plus the Cmd/Ctrl+K dialog, powered by Pagefind. Defaults to `true`.
	 *
	 *  Set to `false` to omit the search chrome entirely: the `search` client
	 *  behavior is never initialized and the trigger button is not rendered in
	 *  any layout. Leave it enabled (the default) to keep the button; note that
	 *  results only appear once a Pagefind index has been built and served at
	 *  `/pagefind/` — see the "Setting up search" guide. Until then the button
	 *  opens to a graceful "Search is not available." message. */
	search?: boolean;
	/** Syntax highlighting options */
	highlight?: {
		theme?: string | { light: string; dark: string };
	};
	/** Custom icon SVGs — merged into the theme's global icon group */
	icons?: Record<string, string>;
	/** Plugins to merge into this site's ThemeConfig (runes, layouts, hooks, etc.) */
	plugins?: string[];
	/** SPEC-035 — active locale (BCP 47, e.g. `'de'`). Selects first-party and
	 *  plugin translation bundles and drives locale-aware formatting. Defaults to
	 *  `'en'` (zero-config English). */
	locale?: string;
	/** SPEC-035 — site-level translation overrides, keyed by the auto-derived
	 *  i18n key (`{scope}.{block}.{ref}`). Highest precedence — these win over
	 *  first-party and plugin bundles (Decision D5). Values are `string` or a
	 *  CLDR plural-category map. */
	strings?: Record<string, string | Record<string, string>>;
	/** Project-level tint presets — merged after theme tints (last wins).
	 *  Field shape matches `TintDefinition` from `@refrakt-md/transform` per
	 *  SPEC-053; `Record<string, unknown>` is used here to avoid a cross-package
	 *  type dependency in `@refrakt-md/types`. */
	tints?: Record<string, Record<string, unknown>>;
	/** Project-level background presets — merged after theme backgrounds (last wins) */
	backgrounds?: Record<string, Record<string, unknown>>;
	/** Sandbox configuration. The runtime program-source directory (SPEC-104). */
	sandbox?: {
		/** Directory of sandbox program sources, scanned at build time
		 *  (ADR-022). Relative to the project root. */
		dir?: string;
		/** @deprecated Renamed to `dir` (ADR-022). Still accepted as input — the
		 *  config normalizer coalesces it into `dir` and emits a deprecation
		 *  warning — but will be removed in a future release. */
		examplesDir?: string;
	};
	/** Content validation (SPEC-132). The build runs `Markdoc.validate()` over
	 *  every page and reports findings as pipeline warnings; nothing is rendered
	 *  into the page. Omit for the documented defaults.
	 *
	 *  `critical` findings are reported whatever is set here — they mean the
	 *  document could not be understood, which is not a matter of preference
	 *  (D11). Suppression is per-site and per-error-id only: there is
	 *  deliberately no per-page or per-tag switch, because that granularity
	 *  silences the one call site that revealed a real bug (D5). */
	validation?: {
		/** `false` stops reporting every suppressible finding for this site. */
		enabled?: boolean;
		/** Replace the default error ids entirely. Adding `variable-undefined`
		 *  is a mistake the framework will let you make — see D4. */
		ids?: string[];
		/** Error ids to stop treating as problems. Demoted to `info` rather than
		 *  dropped, so they stay visible without adding build-summary noise. */
		disableIds?: string[];
	};
	/** Base URL for canonical links and og:url */
	baseUrl?: string;
	/** Human-readable site name for og:site_name */
	siteName?: string;
	/** Default og:image for pages without their own image */
	defaultImage?: string;
	/** Site logo for Organization JSON-LD schema */
	logo?: string;
	/** Canonical GitHub (or compatible) repository URL — e.g.
	 *  `"https://github.com/owner/repo"`. Used by file-ref (SPEC-078) to
	 *  build deep-link "View source" 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. */
	repoUrl?: string;
	/** Git ref appended to GitHub source URLs (branch / tag / commit SHA).
	 *  Defaults to `"main"` when omitted. Use a commit SHA for archival
	 *  URLs that won't drift when the file is edited later. */
	repoBranch?: string;
	/** Rune resolution configuration */
	runes?: {
		/** Which provider wins a rune name more than one provides: a plugin's
		 *  short name, `"__core__"` to keep a core rune, or `"__project__"` to
		 *  let a project rune shadow a plugin's (SPEC-153 D8). */
		prefer?: Record<string, string>;
		aliases?: Record<string, string>;
		/** Unpublished plugin development: rune name → a JS module exporting a
		 *  rune entry with a `transform`. Not for composed rune definitions,
		 *  which go in `dir` (SPEC-153 D7). */
		local?: Record<string, string>;
		/** SPEC-153 D4 — the project's directory of composed rune definitions,
		 *  relative to the project root. Every `<rune>.md` in it is a composed
		 *  rune named after the file, read through `ProjectFiles` (D5). Defaults
		 *  to `runes`; an absent directory defines no runes. */
		dir?: string;
	};
}