File Paths
Table of Contents
1. Intro
One single website can depend on templates and static assets distributed in a few different places. There are a few key assumptions that govern how weblorg look for files within these directories. Let's see the most notable ones.
2. The site theme
A weblorg website can ship its own templates and static assets by
creating the directories $SITE/theme/templates
and
$SITE/theme/static
respectively. Directories in the user's
website directory have precedence over directories within a theme.
See more below about that.
If an external theme does the job for you, these directories aren't needed at all. They're completely optional and only useful for who is either creating their own themes or adding/overriding to the theme they're using.
3. An external theme directory
It is possible to create themes and ship them separately from
weblorg and weblorg itself ships with a few themes. Both 3rd party
and built-in themes might provide the directories $THEME/templates
and $THEME/static
. Notice that websites default to using a
default theme from one of those shipped with weblorg, though that
can be disabled. See more below.
4. Path resolution
Both templates and static files have the same path resolution. The site theme directory has precedence over the external theme directory:
template_path = $site/templates:$theme/templates static_path = $site/static:$theme/static
Note: in case of static files, that means that files will be copied to the output directory from right to left. That allows static files within the site theme to override files from the external theme.
5. Default external theme
For a smooth experience, weblorg comes configured to use a default theme. Users can either choose a different external theme or disable them completely. A good reason for disabling a theme is to use weblorg-copy-static to copy only the static files of the site theme.