This chapter provides an exhaustive list of all configuration settings, command-line options and template bindings of Soho. If you did not do so yet, you may want to have a look at the Tutorial first.

Configuration file settings

The configuration file (usually named is a standard Python module that may define the following variables:


The directory where assets (images, stylesheets, etc.) live. Must be set to None if no such directory exists.

Default: './assets'.


If set, process only assets, not source files. This may be useful if the only changes are on the CSS, for example.

Default: False.


The base URL of the web site. This is used only to generate the URLs in the Sitemap. If you want the Sitemap to have valid URLs, this variable must be set.

Default: ''


If set, no directories nor files are created. This can be useful to test a new configuration. Note that you can combine this setting with force (see below): nothing will be created either.

Default: False


If set, force the generation of HTML files, even if they have already been generated and are up to date. Note that you can combine this setting with do_nothing (see above).

Default: False


If set, /index.html suffixes are removed from:

  • the path key that is automatically added in the md binding passed to the template (see Template bindings (metadata) below);
  • URLs in the Sitemap (if a Sitemap is generated).

Default: True


A (possibly empty) sequence of regular expressions. If the path of a file matches one of these expressions, it will not be processed.

Default: ('.*\.DS_Store$', '.*~$')


The directory where translations are stored. Must be set to None if no such directory exists.

Default: './locale'.


The minimum level of the messages that will be logged. Must be one of debug, info, warning or error.

Default: 'info'.


The path to the log file. If set to - (a single dash), messages will be logged on the standard output. If a path is provided, it must be an absolute path.

Default: '-'


The directory where the web site will be generated. This directory will be created if it does not exist.

Default: './www'


The directory where source files live.

Default: './src'


The name of the Sitemap file. Must be set to None if you do not want such a file to be generated.

Default: 'sitemap.xml'

The filename of the template to use. It must not be a relative or absolute path to the file (like /path/to/templates/ but only a filename (

The directory where templates live.

Default: './templates'


All directories (except www_dir) are expected to exist. If you do not need the feature, you must set the path to None.

Also, each directory may be an absolute path or a relative path. If it is a relative path and starts with ./ (more precisely a dot followed by the separator on your operating system), the path is supposed to be relative to the directory of the configuration file. For example, './www' will indicate a directory named www next to the configuration file. If the given path is a relative path and does not start with ./, then the path will be relative to the working directory.

Default values can be found in the soho.defaults module and reused in your own configuration file:

import soho.defaults

ignore_files = soho.defaults.DEFAULT_IGNORE_FILES + (
    # Sass source files and cache

Command-line options

soho-build accepts the following command-line options:

-a, --assets-only
See assets_only setting above.
Use CONFIG_FILE as the configuration file. By default, Soho uses a file named in the working directory.
-d, --dry-run, -do-nothing
See do_nothing setting above.
-f, --force
See force setting above.
-h, --help
Show all command-line options.
-v, --version
Show the version number.

Template bindings (metadata)

For each source file that is processed, the template receives two bindings:

The HTML fragment as a string.

A dictionary that contains the specific metadata of the source file (which inherits from the metadata of its directory, recursively) plus the following key:


The URL to the generated file relative to the root of the site. It always starts with a /.

For example, the source file in src/foo/bar/file.html would have a path equal to /foo/bar/file.html.