Config options

kilim.config.ts default-exports defineConfig({ ... }). Every option is optional. The config is checked when it loads: an unknown option or a wrong value stops the command with the option's name, e.g. kilim.config.ts: "timezone" must be an IANA time zone such as "Europe/Istanbul" or "UTC".

import { defineConfig } from "@kilim-dev/core";

export default defineConfig({
  title: "My Blog",
  url: "https://example.com",
  description: "Notes on building fast sites.",
  timezone: "Europe/Istanbul",
  theme: "default",
});

url takes an http or https origin without a path. Canonical links, Open Graph tags, JSON-LD, sitemap.xml, feeds and Open Graph images need it; without it they are left out and the build warns.

titleTemplate must contain %s. Without one, pages are titled Page | Site title, or just Page when there is no title. A page whose title is the site title, such as a home page, keeps it as it is.

timezone is used for dates without an offset (date: 2026-11-01 is midnight there), for the :year, :month and :day of permalink patterns and for showing dates in the theme. trailingSlash is explained under URLs.

export default defineConfig({
  markdown: {
    // Code block languages left plain without a warning.
    ignoreLanguages: ["mermaid"],
    // Gives headings an id from their text or a trailing {#id}.
    headingIds: true,
  },
});

A name is the folder themesDir/<name>/ when it exists, else the package @kilim-dev/theme-<name>, kilim-theme-<name> or <name>. Without a theme, pages get a minimal HTML skeleton. The theme's settings are not in the config: they live in settings/<theme>.yaml (and settings/<theme>.<locale>.yaml per language), only the ones that differ from the theme's defaults, checked when the site builds. Kilim 0.1's themeSettings, i18n.themeSettings and theme-settings.yaml stop the build with where to move them. See Using a theme.

export default defineConfig({
  images: {
    widths: [640, 960, 1280, 1920],
    formats: ["avif", "webp"],
    sizes: "(min-width: 48rem) 48rem, 100vw",
    quality: 75,
  },
});

The main image is the first image in <main>; on a block page, only the first block is searched, since later blocks are usually below the first screen. It loads eagerly with fetchpriority="high" and a preload hint in <head>. An image that sets loading or another fetchpriority itself keeps it, and lcp: false leaves every image lazy.

The _headers file (read by hosts such as Cloudflare Pages and Netlify) gets a Content-Security-Policy. Scripts are limited to the site's own files and what the build added; styles, images, fonts, media and frames may come from any HTTPS site. Without plugins that add scripts, the policy is:

default-src 'self'; script-src 'self' 'inline-speculation-rules'; style-src 'self' 'unsafe-inline' https:; img-src 'self' data: https:; font-src 'self' data: https:; media-src 'self' https:; frame-src 'self' https:; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self' https:; frame-ancestors 'self'

An object replaces or adds directives, and an empty string removes one; false leaves the header out:

export default defineConfig({
  csp: { "img-src": "'self'", "frame-ancestors": "'none'" },
});

These three are shorthands for the built-in plugins of the same name. false turns one off; feed also takes the options of feed():

Configure a built-in plugin either here or in plugins, not both. robots.txt is always written; it points at the sitemap when there is one.

import { defineConfig } from "@kilim-dev/core";
import { git } from "@kilim-dev/core/adapters";
import { search } from "@kilim-dev/core/plugins";

export default defineConfig({
  plugins: [search()],
  audit: { rules: { "meta/title-length": ["warn", { max: 70 }] } },
  deploy: git({ branch: "gh-pages" }),
});

Plugin names must be unique. The adapter's options are checked when the config loads, and an error names the line, e.g. kilim.config.ts:13: "deploy.branch": ....

Paths are relative to the project root.

overridesDir must not overlap layoutsDir, componentsDir or blocksDir.