Metadata-Version: 2.4
Name: bssg
Version: 0.2.0
Summary: Static site generator based on staticjinja with support for templates (Jinja), translations (pyBabel), optimized thumbnail generation (Pillow), and build size minimization by excluding unreferenced files.
Author-email: Bieito Beceiro <eu@bieito.dev>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://gitlab.com/bieito/staticsitegenerator/
Project-URL: Repository, https://gitlab.com/bieito/staticsitegenerator/
Project-URL: Issues, https://gitlab.com/bieito/staticsitegenerator/-/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: staticjinja>=1.0.4
Requires-Dist: Babel>=2.9.0
Requires-Dist: pillow>=8.2.0
Requires-Dist: python-slugify>=7.0.0
Dynamic: license-file

# bSSG – B Static Site Generator
bSSG is an extensible static site generator built on top of [staticjinja](https://github.com/staticjinja/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](#configuration-file)).
3. Write Jinja templates. Use `_('...')` for translatable strings and the available filters (see [Filters and Variables](#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`](https://babel.pocoo.org/en/latest/api/dates.html#babel.dates.format_date).
