Configuration reference

This page lists every field in riebeckite.config.ts. For how the configuration is resolved (filesystem roots, content selection, publishing rules), see Configuration.

Writing the config file

Create riebeckite.config.ts at the application root and export the result of defineConfig.

import { defineConfig } from "@riebeckite/core";
 
export default defineConfig({
  site: {
    title: "My site",
    baseUrl: "https://example.com",
  },
});

defineConfig is a type-checking helper: it returns its argument unchanged and adds no runtime behavior. Keep export default as the config entry so the integration can import it.

Riebeckite resolves the config file from configRoot. For the Vite integration this defaults to the application root, and the file name defaults to riebeckite.config.ts. The CLI searches parent directories from the current directory and also accepts riebeckite.config.js and riebeckite.config.mjs. If the file lives elsewhere or has a different name, pass configRoot and configFile to riebeckiteVite().

Top-level sections

Only site is required. Every other section falls back to the default in its table.

site

site identifies the site and supplies fallbacks for page metadata.

title must be a non-empty string. baseUrl must be an absolute HTTP(S) URL when set. The remaining strings may be omitted or empty.

site.feed

feed.title and feed.description fall back to site.title and site.description; feed.language falls back to site.locale.

site: {
  title: "My site",
  description: "Notes and writing",
  baseUrl: "https://example.com",
  locale: "ja_JP",
  feed: { language: "ja" },
}

content

content.directory

A relative directory resolves against the application root (appRoot), never against configRoot or process.cwd(). See Filesystem roots and external vaults.

content.source

Set source to replace the filesystem reader with another source, such as a remote store. Do not configure directory and source as two readers for the same content.

type ContentSource = {
  scan(): Promise<readonly ContentSourceEntry[]>;
  read(entry: ContentSourceEntry): Promise<string | Uint8Array>;
};
 
type ContentSourceEntry = {
  path: string;
  metadata?: {
    modifiedAt?: number;
    size?: number;
    etag?: string;
    hash?: string;
  };
};

scan returns the logical paths to load. read returns one entry's content as a string or bytes. Metadata is optional and used by the cache.

content.exclude

Patterns match logical paths. * matches within one path segment, ** matches across segments, and ? matches one character.

content: {
  directory: "content",
  exclude: ["drafts/**", "**/private/**", ".obsidian/**"],
}

Excluded files never enter the content pipeline, so they are unavailable for links, graph analysis, and diagnostics. This differs from draft and unlisted, which stay in the content system but are hidden from routes or discovery. See Publishing state.

content.filters.publishStrategy

Frontmatter visibility and publishAt take precedence over the strategy. The full decision table is in Publishing state.

theme

theme accepts either a raw ThemeConfig object or a theme returned by defineTheme. With a raw object or no theme at all, the default theme stylesheet is used. A declared theme supplies its own stylesheets.

Raw ThemeConfig

theme.tokens

Each token maps to a --rb-* custom property. See Design tokens for the full mapping.

theme.tokens is emitted as an unlayered :root { --rb-* } rule after the theme stylesheet, so a value set here overrides the theme's value in every mode (light, explicit dark, and system dark). Adjust accents and surfaces here instead of copying theme CSS.

theme: {
  colorMode: "system",
  typography: "serif",
  articleLayout: "sidebar",
  tokens: { color: { accent: "#c2410c" } },
  userCss: ["/app/custom.css"],
}

Declared themes

A theme package exposes a factory. Pass its options and hand the result to theme.

import { rerurateTheme } from "@riebeckite/theme-rerurate";
 
export default defineConfig({
  site: { title: "My site" },
  theme: rerurateTheme({ colorMode: "system", motion: true }),
});

Theme-specific options are owned by the theme package, not by Core. See Theme system.

plugins

plugins is an array of plugin instances. false, null, and undefined are dropped, so a boolean can toggle a plugin.

plugins: [
  obsidianMarkdown(),
  enableSearch && searchPlugin(),
]

Resolution removes disabled inputs, orders enabled plugins by order, and validates capabilities. Two enabled plugins that share a name fail resolution. Each plugin's validateOptions runs while the config is resolved.

Individual plugin options are documented in the plugin guides and the Plugin system.

cache

cache controls the persistent build cache.

Disabling the cache or moving its directory affects build time only, not the output. See Build cache.

Validation

An invalid configuration throws ConfigValidationError, which lists each offending path and message. Do not catch and ignore it. Run check after any change:

npm exec riebeckite check

See also

• Configuration — roots, content selection, publishing
• Plugin system — the plugin contract
• Theme system — design tokens and the CSS contract
• CLI — check, doctor, and inspect