~/tilder/, Documentation/, Guide/, Getting started

getting started - install tilder and build a first site

tilder runs from its Docker image or from a checkout with Python 3.11 or later; nothing else is required. This page copies the starter site, a small bilingual site with its own theme, builds it, keeps it rebuilding as you write, and tours what the build leaves in public/.

The repository's starter/ folder is a complete site: a landing page, a blog with one post, a 404 page, English and French, and a minimal theme on system fonts. Copy it and make it yours:

git clone --branch v1.4.1 https://github.com/THOSTED/tilder
cp -r tilder/starter my-site
cd my-site

Skip the clone if you already made it to run tilder with Python.

It holds the three folders of every project: content/ (the pages and site.toml), theme/ (how it looks) and assets/ (the logo). The project page describes each one.

The starter declares two languages. For a site in one language, delete content/site.fr.toml, every .fr.md file, and the languages line of content/site.toml.

With Docker, from my-site/:

mkdir -p public
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

-u makes you the owner of what the build writes; creating public/ first keeps Docker from creating it as root.

With Python, from my-site/, next to the tilder/ checkout:

python3 ../tilder/build.py

tilder builds the current folder when it has a content/ folder, into its public/. From anywhere else, name both: --root is the project to build, --out where the site goes.

python3 tilder/build.py --root my-site --out my-site/public

The build prints what it found, then every file it wrote:

$ 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, ...

A second build writes only what changed, and deletes from the output folder every file the build no longer produces: the folder belongs to tilder, keep nothing else in it.

A problem in the content stops the build with a message that names the file and says what to do; the exit code is then 1. A warning, such as an image without alt text or a description too long for search engines, does not stop it. Every message is listed in the command-line reference.

--watch builds once, then watches the project and rebuilds on every change:

python3 ../tilder/build.py --watch

The image's default command is the same watch, on /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

It looks at content/, theme/ and assets/ every second. A build that fails keeps the last good output and waits for the next change. A change to the generator itself, or to a theme's Python types in theme/types/, restarts the process so the new code is loaded.

It also rebuilds at midnight, with no change at all: the build's date decides which events are upcoming and which are past, so an event moves to the past list the day after its date. Midnight is the machine's: in a container, UTC unless the TZ variable says otherwise.

To browse it, serve the folder: the links have no .html, so opening the files from the disk breaks them, and the compose stack of deployment serves them as intended. The build wrote:

A site with events also gets their RSS feed and an iCalendar file. None of this is edited by hand, and none of it is committed: public/ is rebuilt from the sources every time.

• the project
• the command line
• deployment