Themes

On your basalt website, a theme is what defines the look, feel, layout, and (if using custom post types) extra functions of your site. basalt-ng themes are built with jinja2 templates.

An example theme is the “minimal” theme in the basalt-themes repository.

The theme in use on a given website is defined in the site configuration (site.json) file

A basalt theme consists of three key parts: A theme definition file (theme.json), one or more jinja2 templates, and static files

The theme definition file should be located in the root of the theme directory, in a file named “theme.json”

Only two properties are mandatory, “name” and “page_template”, however including “license” as an SPDX license identifier, “author” and “description” is good practice.

An example theme definition file from the “minimal” theme is shown below:

{
  "name": "minimal",
  "description": "Minimal theme to focus on your text",
  "license": "BSD-2-Clause",
  "author": "Alice <alicemail@aliceisvery.gay>",
  "page_template": "entrypoint.jinja"
}

The page template is the template that actually gets rendered by basalt during page rendering. It's a good idea to have the page template defined in the theme definition file be something akin to an entrypoint, from which you branch off into other template files you include using jinja.

The variables available that the page templates need to use are detailed on the template variables page.

Files placed in the “static” directory inside the theme directory will be copied into the built site's static directory.

If a file with the same name is present in the site's static directory, it takes precedence over the theme's copy - this is to allow users to override theme files.