~/tilder/, Documentation/, Reference/, The command line

cli - build.py, its options, its messages and its exit codes

tilder is one command, build.py, run with Python 3.11 or later, or inside its Docker image. It builds a project into a folder once, or keeps rebuilding it as you write, or checks the theme without building. Its messages all have one shape, name the file at fault and say what to do.

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 is at the top of a tilder checkout, and at /tilder/build.py in the Docker image, whose default command is a watch of /site into /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

Options may come in any order, except -h and --help, which count only as the first argument; an argument the build does not know is ignored (getting started).

On the standard output, the first build says what it understood, then every build lists what it wrote, or no change; a file it deleted is listed with a -:

$ 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

The languages: line appears only on a site with several languages; the types: line adds the types that come from the theme, ; from theme: talk. With --watch, the build also says when it waits after a failure or restarts on new code. Warnings and errors go to the error output.

An error stops the build. Every message has the same shape:

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

The file is named from the project's root, or from tilder's for one of its own files; the build gathers every problem of a phase before it stops, so one run shows them all.

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

The errors of the configuration and of the languages:

From tilder 1.2, a recursive collection adds three:

The errors of the content and the theme:

A theme's types in Python have errors of their own, from a missing NAME to a marker two types claim, listed with custom types. The errors of --check are listed with checking a theme.

An invalid site.toml, site.<lang>.toml, theme.toml or theme.<lang>.toml always takes this shape, one line and exit status 1, in a one-shot build and with --watch alike; the traceback follows only with --debug. A bug the build cannot name this way still ends a one-shot build with Python's own message and traceback. With --watch, the same bug is one line, error: <Python error>: <what>, and the traceback follows only with --debug.

A warning does not stop the build nor change its exit code: the site is built, with something missing or likely to be cut. Every warning the build can print:

On a site with several languages, every seo: line names the language of the pass, the default one included: seo: [en] about.html: ..., seo: [fr] about.html: ... (SEO). A site that wants no warning at all makes its own build fail on them, as this site's build does on any warning: or seo: line. In a shell script:

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

With --watch, a failed build does not exit: the process keeps waiting for a fix, and runs until it is stopped.

• getting started
• checking a theme
• configuration