bSSG – B Static Site Generator

bSSG is an extensible static site generator built on top of staticjinja. It provides support for templating (Jinja), internationalization (pyBabel), optimized thumbnail generation (Pillow), and build size minimization by excluding unreferenced files.

Features

• Templating support via Jinja
• Internationalization via pyBabel
• Responsive thumbnail generation using Pillow
• Output minimization by including only referenced static files
• Support for loading user-defined data (JSON) into templates

Architecture

A site that uses bSSG will have a source structure as:

input/
 +- templates/
 |   +- <tree>
 +- static/
 |   +- <static files to use in templates>
 +- translations/
     +- <language code>/
     |   +- LC_MESSAGES/
     |       +- messages.po
     ...

The generated site has the following structure:

build/
 +- <language code>/
 |   +- <tree>
 ...
 +- <static files used in templates>
 +- thumb/
     +- <generated thumbnails>

After generation, the site can be accessed via URLs of the form: {URL_PREFIX}/[{LANG_CODE}/]{SUFFIX}. Since the output is static, a web server must be configured so that URL_PREFIX maps to the build directory.

An optional STATIC_PREFIX can be used to group static files under a dedicated path instead of placing them at the root. Thumbnails are generated within the static directory, but an additional THUMB_PREFIX can be configured to isolate them in a separate subdirectory.

Usage

To create a website with bSSG:

1. Generate the default configuration file: bssg init. By default, this creates bssg.toml. A custom path can be specified with --cfg <file>.
2. Edit the configuration file as needed (see Configuration File).
3. Write Jinja templates. Use _('...') for translatable strings and the available filters (see Filters and Variables).
4. Handle translations (if applicable). NOTE: steps 4.1 and 4.2 are automated with bssg get-translations and step 4.4 is performed during bssg build.
   1. Extract the strings from the templates to a .pot file.
   2. Initialize or update .po files (one for each language).
   3. Edit the translations in .po files.
   4. Compile catalogs into .mo files (done automatically during build).
5. Build the site: bssg build. This compiles translations, generates thumbnails, and renders the site.
6. Copy static files: bssg copy-static. Only files referenced at least once are copied.

Configuration File

The configuration file uses TOML format. By default, it is bssg.toml, but a different file can be specified with --cfg <file>.

It is divided into three sections: [site], [paths], and [data].

[site]

Defines URL structure and language behavior:

• url_prefix: base URL of the site.
• languages: list of supported language codes.
• root_language (optional): language served at the root (<url_prefix>/...). Other languages are served under <url_prefix>/<lang_code>/.... Useful for single-language sites or when defining a primary language.
• static_prefix (optional): prefix for static assets (<url_prefix>/<static_prefix>/...).
• thumb_prefix (optional): prefix for generated thumbnails within the static directory.

[paths]

Defines input and output directories:

Input

• templates: Jinja templates.
• locale: translation files (pyBabel).
• static: static assets (CSS, JS, images).

Output

• cache: intermediate build data.
• build: output directory for the generated site.

[data]

Defines custom data sources with the format <var_name> = <path_to_json>. Each JSON file is loaded and exposed to templates under <var_name>.

Filters and Variables

The following variables and filters are made available in templates:

Variables

• url_prefix: base URL from configuration.
• language: current language code.
• languages: list of configured languages.
• timestamp: value of datetime.datetime.now() at build start (constant across all templates and languages).
• generator: name and version of the generator (staticjinja).
• Any <var_name> defined in [data], containing the parsed JSON data.

Filters

• absolute(url): returns <url_prefix>/<url> (does not include language prefix).
• static(path): registers a static file and returns its relative URL. Can be combined with absolute for full URLs.
• urltranslate(url, lang_code=None): adds a language prefix to url. Defaults to the current language.
• thumb(path, width, aspect=None, suffix=".webp"): registers an image for thumbnail generation and returns its (static) URL.
  • width: required (pixels).
  • aspect: optional aspect ratio (defaults to original).
  • suffix: output format (default: .webp).
• thumbs(path, widths, fn=None, aspect=None, suffix=".webp"): generates multiple thumbnails for responsive images, returning a list formatted for the HTML srcset attribute ("<url> <width>w").
  • widths: list of widths.
  • fn: optional function applied to each URL (e.g., the absolute filter).
  • datefmt: alias for babel.dates.format_date.