~/tilder/, fr/, Documentation/, Référence/, La ligne de commande

cli - build.py, ses options, ses messages et ses codes de sortie

tilder tient en une commande, build.py, lancée avec Python 3.11 ou plus récent, ou dans son image Docker. Elle construit un projet dans un dossier, une fois, ou le reconstruit à mesure que vous écrivez, ou vérifie le thème sans rien construire. Ses messages ont tous la même forme : ils nomment le fichier en cause et disent quoi faire.

python3 build.py [--root DIR] [--out DIR] [--watch] [--debug]
python3 build.py [--root DIR] --check [--markdown] [--debug]
python3 build.py --version
python3 build.py -h | --help

build.py se trouve à la racine d'une copie de tilder, et à /tilder/build.py dans l'image Docker, dont la commande par défaut surveille /site et construit dans /out :

docker run --rm -u "$(id -u):$(id -g)" \
  -v "$PWD:/site" -v "$PWD/public:/out" \
  ghcr.io/thosted/tilder:1.4.1 \
  python3 -B /tilder/build.py --root /site --out /out

Les options viennent dans n'importe quel ordre, sauf -h et --help, qui ne comptent qu'en premier argument ; un argument que la construction ne connaît pas est ignoré (premiers pas).

Sur la sortie standard, la première construction dit ce qu'elle a compris, puis chaque construction énumère ce qu'elle a écrit, ou no change ; un fichier supprimé apparaît précédé d'un - :

$ python3 ../tilder/build.py
languages: en (default), fr
types: event, member, page, post
collections: blog (post, 1 item), events (event, no folder), ...
[10:42:07] built /home/me/my-site/public: 404.html, blog/feed.xml, ...
[10:43:12] built /home/me/my-site/public: about.html, txt/about.txt, ansi/about.txt
[10:44:30] built /home/me/my-site/public: -old.html

La ligne languages: n'apparaît que sur un site en plusieurs langues ; la ligne types: ajoute les types qui viennent du thème, ; from theme: talk. Avec --watch, la construction dit aussi quand elle attend après un échec ou redémarre sur du nouveau code. Les avertissements et les erreurs vont sur la sortie d'erreur.

Une erreur arrête la construction. Chaque message a la même forme :

error: <file>[:<line>]: <what is wrong>. <what to do>

Le fichier est nommé depuis la racine du projet, ou depuis celle de tilder pour l'un de ses propres fichiers ; la construction rassemble chaque problème d'une étape avant de s'arrêter, si bien qu'un seul lancement les montre tous.

error: content/site.toml: collection "blog" has type "posts"; types are singular. Write type = "post"
error: content/blog/2026-02-30-hello.md: "2026-02-30" is not a date. Name the file YYYY-MM-DD-slug.md with the post's date

Les erreurs de la configuration et des langues :

Depuis tilder 1.2, une collection récursive en ajoute trois :

Les erreurs du contenu et du thème :

Les types en Python d'un thème ont leurs propres erreurs, d'un NAME manquant à un marqueur que deux types revendiquent, décrites dans vos propres types. Les erreurs de --check sont décrites dans vérifier un thème.

Un site.toml, site.<lang>.toml, theme.toml ou theme.<lang>.toml invalide prend toujours cette forme, une ligne et un code de sortie 1, dans une construction unique comme avec --watch ; la trace ne suit qu'avec --debug. Un bogue que la construction ne peut nommer ainsi termine encore une construction unique par le message et la trace de Python lui-même. Avec --watch, ce même bogue tient en une ligne, error: <erreur Python>: <quoi>, et la trace ne suit qu'avec --debug.

Un avertissement n'arrête pas la construction et ne change pas son code de sortie : le site est construit, avec quelque chose qui manque ou qui risque d'être tronqué. Chaque avertissement que la construction peut écrire :

Sur un site en plusieurs langues, chaque ligne seo: nomme la langue de la passe, celle par défaut comprise : seo: [en] about.html: ..., seo: [fr] about.html: ... (SEO). Un site qui ne veut aucun avertissement fait échouer sa propre construction dessus, comme la construction de ce site le fait sur toute ligne warning: ou seo:. Dans un script shell :

python3 ../tilder/build.py 2> build.log; status=$?
cat build.log >&2
[ "$status" -eq 0 ] && ! grep -Eq '^(warning|seo):' build.log

Avec --watch, une construction qui échoue ne fait pas sortir : le processus attend une correction, et tourne jusqu'à ce qu'on l'arrête.

• premiers pas
• vérifier un thème
• la configuration