refrakt.md

Docs Runes Plan Blog Changelog

Configuration Reference

Every refrakt.md project has a refrakt.config.json file at its root. This file tells the framework where your content lives, which theme to use, and which adapter and packages to load.

Minimal example

{
  "contentDir": "./content",
  "theme": "@refrakt-md/lumina",
  "target": "svelte"
}

Required fields

FieldTypeDescription
contentDirstringPath to the content directory, relative to the project root
themestringActive theme — an npm package name (e.g., @refrakt-md/lumina) or a relative path to a local theme
targetstringTarget adapter identifier (e.g., svelte, astro, next, nuxt, eleventy, html)

Optional fields

baseUrl

{
  "baseUrl": "https://example.com"
}

The public base URL of your site. Used to generate absolute URLs for <link rel="canonical">, og:url, and other SEO meta tags. Without this, canonical links and Open Graph URLs will use relative paths.

siteName

{
  "siteName": "My Site"
}

Human-readable site name, used in the og:site_name meta tag. If omitted, defaults to "refrakt.md" in the Svelte adapter.

packages

{
  "packages": [
    "@refrakt-md/marketing",
    "@refrakt-md/docs"
  ]
}

An array of community rune package names to load. Packages are npm modules that export a RunePackage object. Their rune schemas, theme configs, and pipeline hooks are merged into the build automatically.

See Community Packages for the full list of official packages.

runes

Controls rune name resolution — useful when multiple packages define runes with the same name or when you want shorthand aliases.

{
  "runes": {
    "prefer": {
      "timeline": "@refrakt-md/business"
    },
    "aliases": {
      "callout": "hint",
      "note": "hint"
    },
    "local": {
      "custom-card": "./runes/custom-card.ts"
    }
  }
}
Sub-fieldTypeDescription
preferRecord<string, string>Resolve name collisions between packages. The value is the package that wins. Use "__core__" to force the core version.
aliasesRecord<string, string>Tag name aliases — use {% callout %} as shorthand for {% hint %}
localRecord<string, string>Local rune module paths (highest priority). Keys are tag names, values are relative paths to schema files.

overrides

{
  "overrides": {
    "Recipe": "./components/MyRecipe.svelte",
    "Hero": "./components/MyHero.svelte"
  }
}

Component override mapping. Keys are typeof names (the rune's component identifier), values are relative paths to replacement components. This lets you swap out the default rendering for any rune without modifying the theme.

routeRules

{
  "routeRules": [
    { "pattern": "blog/**", "layout": "blogArticleLayout" },
    { "pattern": "docs/**", "layout": "docsLayout" },
    { "pattern": "**", "layout": "defaultLayout" }
  ]
}

An array of route-to-layout rules, evaluated in order (first match wins). Each rule has a pattern (glob matched against the page URL) and a layout (layout name from the theme).

highlight

{
  "highlight": {
    "theme": "github-dark"
  }
}

Or with separate light/dark themes:

{
  "highlight": {
    "theme": {
      "light": "github-light",
      "dark": "github-dark"
    }
  }
}

Syntax highlighting configuration. The theme field accepts a single theme name or a { light, dark } pair for dual-mode highlighting.

icons

{
  "icons": {
    "rocket": "<svg>...</svg>",
    "custom-logo": "<svg>...</svg>"
  }
}

Project-level custom icon SVGs. These are merged into the theme's global icon group and become available to the {% icon %} rune and any structure entries that reference icons by name.

tints

{
  "tints": {
    "brand": {
      "bg": "var(--rf-color-brand-50)",
      "border": "var(--rf-color-brand-200)"
    }
  }
}

Project-level tint presets, merged after the theme's built-in tints. Tints are named color schemes that runes can reference via the tint attribute (e.g., {% hint tint="brand" %}).

backgrounds

{
  "backgrounds": {
    "hero-gradient": {
      "background": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
    }
  }
}

Project-level background presets, merged after the theme's built-in backgrounds. Used by runes like {% bg %} and {% hero %}.

sandbox

{
  "sandbox": {
    "examplesDir": "./examples"
  }
}

Configuration for the {% sandbox %} rune. The examplesDir field sets the directory where external sandbox example files are stored (defaults to ./examples).

Full example

{
  "contentDir": "./content",
  "theme": "@refrakt-md/lumina",
  "target": "svelte",
  "baseUrl": "https://example.com",
  "siteName": "My Documentation",
  "packages": [
    "@refrakt-md/marketing",
    "@refrakt-md/docs",
    "@refrakt-md/design"
  ],
  "runes": {
    "prefer": {
      "storyboard": "@refrakt-md/marketing"
    },
    "aliases": {
      "callout": "hint"
    }
  },
  "overrides": {
    "Recipe": "./components/MyRecipe.svelte"
  },
  "routeRules": [
    { "pattern": "blog/**", "layout": "blogArticleLayout" },
    { "pattern": "**", "layout": "defaultLayout" }
  ],
  "highlight": {
    "theme": { "light": "github-light", "dark": "github-dark" }
  },
  "icons": {
    "custom-logo": "<svg viewBox='0 0 24 24'>...</svg>"
  }
}