~/tilder/, fr/, Documentation/, Référence/, Configuration

configuration - chaque clé de defaults.toml

tilder lit chaque réglage d'un site, et chaque mot qu'un lecteur voit en dehors des pages, dans des fichiers TOML. Son propre defaults.toml contient chaque clé avec une valeur par défaut neutre, en anglais ; le theme.toml du thème et le content/site.toml du site se fusionnent par-dessus, et ne disent que ce qui change. Cette page reprend chaque clé de defaults.toml, table par table, avec sa valeur par défaut telle que le fichier l'écrit.

Chaque fichier se fusionne par-dessus le précédent, le dernier l'emporte : defaults.toml, puis theme/theme.toml, puis content/site.toml. Sur un site en plusieurs langues, theme/theme.<lang>.toml vient après theme.toml, et content/site.<lang>.toml après site.toml, pour la passe de cette langue (le projet, langues).

• Les tables se fusionnent clé par clé : un fichier qui règle [site] manual garde toutes les autres clés de [site].
• Une valeur qui n'est pas une table, liste comprise, remplace la précédente en entier. Une liste de tables, [[nav]], aussi : un fichier qui la règle en répète chaque entrée.
• Les réglages d'une collection partent des valeurs par défaut de son type, dans le module du type, avec [collections.<name>] par-dessus (types de contenu).

Les fichiers sont relus à chaque construction, et aucun n'est jamais servi. Une clé que tilder ne lit pas est ignorée, sauf les quelques tables retirées, qui arrêtent la construction avec un message disant où sont passées leurs clés (la ligne de commande).

La table [site] : qui est le site, où il vit, sa langue.

site.url doit être l'adresse à laquelle le site est servi : les liens canoniques, og:url, les plans du site, les flux et le calendrier en sont tirés. site.title_suffix n'est ajouté que si le titre ne nomme pas déjà le site, majuscules ou non : une page intitulée About my site garde son titre tel quel.

[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"]

La table [footer] : le filet de pied de page de manuel, en bas de chaque page, avec site.updated en son milieu.

Le miroir en texte écrit lui-même le filet à partir de ces clés. Sur la page, le gabarit les place où il veut : celui du site de départ écrit <a href="{{ home }}{{ footer.left_link }}">{{ footer.left }}</a> (gabarits et variables).

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

La table [labels] : les mots de l'interface, dont beaucoup ne s'entendent qu'à travers un lecteur d'écran. Traduisez-les dans site.<lang>.toml.

Les trois libellés d'encadré choisissent aussi la couleur de la boîte dans le miroir en couleur : la boîte dont le filet du haut porte labels.info suit text.accent, labels.warning est jaune, labels.error rouge (le miroir en texte). Les variables du gabarit ne servent que là où le layout.html du thème les écrit, comme le fait celui du site de départ.

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

La table [links] : les liens externes s'ouvrent-ils dans un nouvel onglet ?

Un lien qui ouvre un nouvel onglet reçoit target="_blank" et rel="noopener", et l'annonce aux lecteurs d'écran avec labels.new_tab. La règle vaut pour les liens des pages, la navigation et les liens de profil d'un membre (écrire des pages).

[links]
new_tab = true
same_tab = ["example.com"]    # et ses sous-domaines

La table [languages] est vide par défaut : elle associe au code d'une langue le nom qu'affiche le sélecteur de langue. Une langue sans nom affiche son code.

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

Les noms ne sont lus que dans la configuration de la langue par défaut : ils s'écrivent une fois, dans site.toml, chacun dans sa propre langue (langues).

La liste de tables [[nav]] : la navigation, dans l'ordre, une table par lien. Par défaut, elle a une entrée.

Une page marque son entrée comme courante avec sa clé d'en-tête nav:, égale au href de l'entrée (écrire des pages). La première entrée est aussi la première étape du fil d'Ariane de chaque page dans les données structurées, et l'entrée que marque la page, sauf la page d'accueil ou un lien externe, la deuxième (SEO). Les liens restent dans la langue courante : about, depuis une page française, mène à /fr/about.

Une liste de tables se remplace en entier : un site qui ajoute un lien les écrit tous, le premier compris.

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

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

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

La table [seo] : les données structurées, la valeur par défaut pour les robots, et les limites des vérifications de la construction (SEO).

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

La table [share] : les icônes, l'aperçu de lien et le manifeste web. Les icônes sont dessinées à chaque construction à partir de assets/logo.svg, et share.png à partir du share.svg du thème, rempli avec les valeurs d'ici (flux et images).

Les cinq couleurs servent au share.svg du thème, qui les lit sous la forme {{ share.text_color }} et ainsi de suite ; un thème les règle d'habitude dans son theme.toml, en accord avec sa palette. Seules theme_color et background_color sont aussi écrites par la construction elle-même, dans le manifeste.

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

[collections.<name>] déclare un dossier de content/ dont les fichiers sont les éléments d'un même type (types de contenu). Ses clés sont les réglages du type, chacun décrit sur la page du type, plus celles-ci :

Depuis tilder 1.2, recursive = true fait des sous-dossiers de dir des sections de la collection, et de leurs fichiers ses éléments, dans l'arbre de la barre latérale (navigation). La valeur est false sauf si la collection ou les DEFAULTS de son type la règlent ; un type daté, comme post ou event, ne peut pas être récursif, et la construction s'arrête s'il l'est.

defaults.toml déclare les trois collections que la plupart des sites ont. Chacune reste inactive tant que son dossier n'existe pas : ni page, ni flux, ni calendrier.

Un site ne règle que ce qui en diffère, ou déclare les siennes :

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

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

Les réglages de chaque type intégré sont sur sa page : post, event, member, page.

La table [dates] : comment une date s'écrit en toutes lettres, sur la carte d'un article ou d'un événement et comme accroche d'un article ou d'un événement.

dates.format prend quatre noms entre accolades : {weekday}, {day} (le numéro du jour, sans zéro devant, ou dates.first le premier du mois), {month} et {year}. Avec les valeurs par défaut, 2026-11-21 s'écrit Saturday 21 November 2026. En français, « 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}"

La table [calendar] : ce que partagent tous les fichiers iCalendar du site, pour les collections qui règlent calendar (event).

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

La table [text] : les couleurs du miroir en texte coloré.

Une ligne de bloc de code qui commence par l'un des mots de text.commands, seul ou après une invite, $ ou # suivi d'une espace, prend la couleur d'accent dans ansi/ ; txt/ n'a aucune couleur (le miroir en texte).

text.accent vaut l'un des huit noms de couleur black, red, green, yellow, blue, magenta, cyan (le défaut), white, ou un index de 256 couleurs de 16 à 255, tel que 208 pour l'orange. Toute autre valeur arrête la construction. Un site.<lang>.toml peut régler son propre accent pour cette langue.

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

Deux tables, une par robots.txt qu'écrit la construction (SEO).

Chaque chemin devient une ligne Disallow: ; une liste vide écrit Allow: / à la place. Le robots.txt du site indique aussi sitemap.xml.

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

La table [check] appartient au thème : lue par build.py --check (tilder 1.2), elle se règle dans theme/theme.toml ; content/site.toml peut aussi la régler, fusionnée par-dessus celle du thème comme toute autre table. unstyled, les classes que le thème laisse sans style à dessein (défaut []) ; contrast, les paires de couleurs à vérifier (défaut [], rien de vérifié) ; contrast_min, le contraste minimal de chaque paire (défaut 4.5). Chaque clé est décrite dans vérifier un thème.

• le projet
• types de contenu
• gabarits et variables
• la ligne de commande