~/tilder/, Documentation/, Reference/, Configuration

configuration - every key of defaults.toml

tilder reads every setting of a site, and every word a reader sees outside the pages, from TOML. Its own defaults.toml holds each key with a neutral, English default; the theme's theme.toml and the site's content/site.toml are merged over it, and state only what differs. This page lists every key of defaults.toml, table by table, with its default exactly as the file writes it.

Each file is merged over the one before, the last one winning: defaults.toml, then theme/theme.toml, then content/site.toml. On a site with several languages, theme/theme.<lang>.toml comes after theme.toml, and content/site.<lang>.toml after site.toml, for the pass of that language (the project, languages).

• Tables merge key by key: a file that sets [site] manual keeps every other key of [site].
• A value that is not a table, a list included, replaces the one before as a whole. So does a list of tables, [[nav]]: a file that sets it repeats every entry.
• A collection's settings start from its type's own defaults, in the type's module, with [collections.<name>] over them (content types).

The files are read again at every build, and none of them is ever served. A key tilder does not read is ignored, except the few removed tables that stop the build with a message saying where their keys went (the command line).

The [site] table: who the site is, where it lives, its language.

site.url must be the address the site is served at: the canonical links, og:url, the sitemaps, the feeds and the calendar are built from it. site.title_suffix is added only when the title does not name the site already, in any case: a page titled About my site keeps its title as it is.

[site]
name = "my site"
url = "https://example.org"
lang = "en"
locale = "en_GB"
manual = "My Site Manual"
updated = 2026-05-16
title_suffix = " - my site"
languages = ["en", "fr"]

The [footer] table: the man-page footer rule at the bottom of every page, with site.updated in its middle.

The text mirror writes the footer rule from these keys itself. On the page, the layout places them where it wants: the starter writes <a href="{{ home }}{{ footer.left_link }}">{{ footer.left }}</a> (layouts).

[footer]
left = "MYSITE"
left_link = "about"
right = "MYSITE(1)"

The [labels] table: the words of the interface, many of them heard only through a screen reader. Translate them in site.<lang>.toml.

The three callout labels also pick the colour of the callout's box in the coloured mirror: the box whose top rule carries labels.info follows text.accent, labels.warning is yellow, labels.error red (the text mirror). The layout placeholders work only where the theme's layout.html writes them, as the starter's does.

# content/site.fr.toml
[labels]
skip = "aller au contenu"
toc = "sommaire"
prev = "précédent"
next = "suivant"

The [links] table: whether external links open in a new tab.

A link that opens a new tab gets target="_blank" and rel="noopener", and tells screen readers so with labels.new_tab. The rule covers links in pages, the navigation and a member's profile links (writing pages).

[links]
new_tab = true
same_tab = ["example.com"]    # and its subdomains

The [languages] table is empty by default: it maps a language's code to the name the language switcher shows. A language without a name shows its code.

[languages]
en = "English"
fr = "Français"

The names are read from the default language's configuration only, so they are written once, in site.toml, each in its own language (languages).

The [[nav]] list of tables: the navigation, in order, one table per link. The default has one entry.

A page marks its entry as the current one with its nav: front-matter key, equal to the entry's href (writing pages). The first entry is also the first step of every page's breadcrumb in the structured data, and the entry a page marks, unless it is the landing page or an external link, is the second one (SEO). Links stay inside the current language: about from a French page leads to /fr/about.

A list of tables is replaced as a whole: a site that adds one link writes them all, the first one included.

[[nav]]
label = "home"
href = ""

[[nav]]
label = "blog"
href = "blog/"

[[nav]]
label = "source ↗"
href = "https://example.com/my-site"

The [seo] table: structured data, the default for robots, and the limits of the build's checks (SEO).

[seo]
organization = "Example Group"
title_max = 65

The [share] table: the icons, the link preview and the web manifest. The icons are drawn at every build from assets/logo.svg, and share.png from the theme's share.svg, filled with values from here (feeds and images).

The five colours are for the theme's share.svg, which reads them as {{ share.text_color }} and the like; a theme usually sets them in its theme.toml, to match its palette. Only theme_color and background_color are also written by the build itself, in the manifest.

[share]
image_alt = "~/my site"
card = ["meetups and talks", "in Exampleville"]
short_name = "mysite"

[collections.<name>] declares a folder of content/ whose files are items of one type (content types). Its keys are the type's settings, each listed on the type's page, plus these:

From tilder 1.2, recursive = true makes the subfolders of dir sections of the collection, and their files its items, in the sidebar's tree (navigation). It is false unless the collection or its type's DEFAULTS sets it; a dated type, such as post or event, cannot be recursive, and the build stops if one is.

defaults.toml declares the three collections most sites have. Each one is inactive until its folder exists: no page, no feed, no calendar.

A site sets only what differs from them, or declares its own:

[collections.blog]
man = "MYSITE-BLOG(7)"
feed_title = "my site blog"

[collections.talks]
type = "event"
feed = "talks.xml"
calendar = "talks.ics"

The settings of each built-in type are on its page: post, event, member, page.

The [dates] table: how a date is written out in words, on a post's or an event's card and as the tagline of a post or an event.

dates.format takes four names in braces: {weekday}, {day} (the day's number, without a leading zero, or dates.first on the first of the month), {month} and {year}. With the defaults, 2026-11-21 is Saturday 21 November 2026. A French site writes "samedi 1er novembre":

# content/site.fr.toml
[dates]
weekdays = ["lundi", "mardi", "mercredi", "jeudi", "vendredi",
            "samedi", "dimanche"]
months = ["janvier", "février", "mars", "avril", "mai", "juin",
          "juillet", "août", "septembre", "octobre", "novembre",
          "décembre"]
first = "1er"
format = "{weekday} {day} {month} {year}"

The [calendar] table: what every iCalendar file of the site shares, for the collections that set calendar (event).

[calendar]
name = "my site events"
prodid = "-//example.org//events//EN"
uid_domain = "example.org"

The [text] table: the coloured text mirror's colours.

A code-block line that starts with one of text.commands, alone or after a prompt, $ or # and a space, is coloured in the accent in ansi/; txt/ has no colour at all (the text mirror).

text.accent is one of the eight colour names black, red, green, yellow, blue, magenta, cyan (the default), white, or a 256-colour index from 16 to 255, such as 208 for orange. Anything else stops the build. A site.<lang>.toml may set its own accent for that language.

[text]
commands = ["curl", "docker", "python3"]
accent = 208

Two tables, one per robots.txt the build writes (SEO).

Each path becomes a Disallow: line; an empty list writes Allow: / instead. The site's robots.txt also points to sitemap.xml.

[robots]
disallow = ["/txt/", "/ansi/", "/drafts/"]

The [check] table is the theme's, read by build.py --check (tilder 1.2) and set in theme/theme.toml; content/site.toml may set it too, merged over the theme's as every other table: unstyled, the classes the theme leaves unstyled on purpose (default []); contrast, the pairs of colours to check (default [], nothing checked); contrast_min, the least ratio of every pair (default 4.5). Every key is described in checking a theme.

• the project
• content types
• layouts
• the command line