GitHub

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#

Helper Purpose
Page(_ title:, _ path:) A markdown page. path is relative to the content directory (the logical path — no locale suffix).
Section(_ title:) { … } A named, collapsible group of pages and/or nested sections.
Link(_ title:, _ url:) An external link rendered in the nav.

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.

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",
])

Tip

Only titles you include in navTranslations are translated; anything left out simply shows in the default language. There’s no need to translate every label at once.

Edit this page