Obraz — static site generator in a single Python file mostly compatible with Jekyll

Obraz Plugins

Plugins allow extending the site generation process via user-defined processing functions.

Consider a photo hosting example. By writing a custom plugin you can:

Plugins are Python files that should be put into the _plugins directory of the site.

Obraz plugins are incompatible with Jekyll plugins, see compatiblity with Jekyll.

Available Plugins

Note: You can add your plugins to this list by sending a pull request to the Obraz repository on GitHub.

Site Model

Internally Obraz represents the site being generated as a Python dictionary. This is the same dictionary as site in Jekyll template data.

The generation process is split into three steps:

  1. Loader functions populate the site dictionary by reading files from the source directory
  2. Processor functions modify the site dictionary (e.g. sort data)
  3. Generator functions create files in the destination directory based on the site dictionary

Functions for all these steps are registered via extension point decorators. This applies to third-party plugin functions as well as to the processing functions in Obraz itself.

There are also a couple of extension points that allow to change define content and template filters, or change the template system.

Extension Points

Development Notes

The easiest way of getting started with plugin development is to read source code of other plugins.

Please document your plugin carefully in the plugin file docstring. Don't forget to mention Obraz version compatiblity, required libraries, configuration parameters.

If a plugin needs configuration parameters, the best place for them is a separate section in _config.yml. The contents of this YAML file will be available for the plugin as a part of site.

You may use all functions defined in obraz, but they are not a part of the plugins API and may be changed or removed in future versions.