Navigation#

The navigation tree is built with a Swift result builder using three helpers:

navigation: {
    Page("Welcome", "index.md")          // a markdown page
    Section("Guides") {                   // a collapsible group
        Page("Configuration", "guides/configuration.md")
        Page("Theming", "guides/theming.md")
    }
    Link("API Reference", "https://example.com/api")  // an external link
}

The three building blocks#

Sections can nest, so you can build multi-level navigation:

Section("Guides") {
    Page("Overview", "guides/index.md")
    Section("Advanced") {
        Page("Theming", "guides/theming.md")
    }
}

Logical paths#

A Page path always points at the default-language file, e.g. guides/configuration.md. Kiln resolves the correct translation (guides/configuration.de.md) per language automatically — see Content & Localisation.

What Kiln derives for you#

From this single tree Kiln computes, for every page and language:

• the active trail (which section/page is highlighted),

• previous / next links following document order, and

• breadcrumbs and the on-page table of contents.

Pages outside the navigation#

Some pages belong on the site but not in the sidebar — a legal notice, a privacy policy, a landing page you link to from a campaign. Declare those as unlistedPages instead of Page entries:

KilnSite(
    name: "Kiln",
    url: "https://kiln.brokenhands.io",
    unlistedPages: [
        UnlistedPage("Legal", "legal.md"),
        UnlistedPage("Draft", "draft.md", searchable: false, indexed: false),
    ]
) {
    Page("Welcome", "index.md")
    Section("Guides") { … }
}

On a versioned site, unlistedPages goes on the DocVersion instead — each version has its own, exactly like navigation.

An unlisted page is built like any other: the full theme, “pretty” URL, translations (legal.de.md), link checking, and an <h1>-derived title. It’s simply absent from the navigation tree, from the previous/next reading order, and from llms.txt (which mirrors the navigation).

Two flags control how discoverable an unlisted page is:

The defaults suit a footer page you want found — a legal or privacy page. Setting both to false gives a page reachable only by direct link.

This site has one: the Legal page linked in the footer. It’s not in the sidebar, but it’s a normal page in every other respect.

Translating labels#

Section and page titles are translated per language with each Language’s navTranslations map, keyed on the default-language title:

.init(.german, navTranslations: [
    "Guides": "Anleitungen",
    "Configuration": "Konfiguration",
])