Configuration#

Everything about your site is described by a single KilnSite value. This page uses a custom front-matter title (see the browser tab) to demonstrate the meta feature.

Fields#

Field	Type	Notes
`name`	`String`	Site title.
`url`	`String`	Canonical site URL (used for sitemap, OpenGraph, hreflang).
`author`	`String?`	Used for meta tags.
`description`	`String?`	Default meta/OpenGraph description.
`image`	`String?`	Default social preview image (content-relative path).
`twitterSite`	`String?`	Handle for the `twitter:site` tag (e.g. `"@brokenhandsio"`).
`repository`	`Repository?`	`name`, `url`, optional `editURI` for “edit this page” links.
`copyright`	`String?`	Footer notice.
`theme`	`Theme`	`.default(…)` or `.custom(directory:…)` — see Theming.
`social`	`[SocialLink]`	Icon + link; shown in the header/footer.
`carbonAds`	`CarbonAds?`	Carbon Ads `serve`/`placement`.
`extraCSS`	`[String]`	Extra stylesheets (content-relative).
`extraJavaScript`	`[String]`	Extra scripts.
`languages`	`[Language]`	See Content & Localisation.
`markdown`	`MarkdownExtensions`	Feature toggles + table-of-contents options.
`navigation`	`@NavBuilder`	The nav tree — see Navigation.

A fuller example#

let site = KilnSite(
    name: "My Docs",
    url: "https://docs.example.com",
    description: "Documentation for My Project.",
    repository: .init(
        name: "GitHub",
        url: "https://github.com/me/project",
        editURI: "https://github.com/me/project/edit/main/Content/"
    ),
    theme: .default(palette: .autoLightDark(primary: .black, accent: .blue)),
    social: [.init(icon: .github, link: "https://github.com/me/project")],
    languages: [
        .init(.english, isDefault: true),
        .init(.german, navTranslations: ["Guides": "Anleitungen"]),
    ],
    navigation: {
        Page("Welcome", "index.md")
        Section("Guides") {
            Page("Configuration", "guides/configuration.md")
        }
    }
)

try await Kiln.build(site, contentDirectory: "Content", outputDirectory: "site")

Languages#

Declare each language you support with a LanguageCode — a built-in case like .english or .german, or .custom(code:name:). Exactly one language must be the default; missing translations fall back to it automatically.

languages: [
    .init(.english, isDefault: true),
    .init(.german, navTranslations: ["Guides": "Anleitungen"]),
    .init(.custom(code: "gd", name: "Gàidhlig")),
]

See Content & Localisation for the full story on translations, fallback, and UI strings.

Theme#

theme: .default(
    palette: .autoLightDark(primary: .black, accent: .blue),
    logo: "assets/logo.svg",
    favicon: "assets/logo.svg"
)

Color accepts presets (.black, .blue, .indigo, …) or any CSS string via Color("#2f6feb"). To replace the theme entirely, use .custom(directory:) and see Theming.

Logical paths

Navigation references the default-language file path (guides/configuration.md). Kiln finds the right translation per language for you — you never hard-code locale-suffixed paths.