Advanced Usage

In the tutorial, you saw an example of a minimal Complexity project layout. Now here is an example of a more advanced Complexity site:

├── project/       <--------- input
│   ├── assets/
│   │   ├── css/
│   │   ├── js/
│   │   ├── img/
│   │   ├── ico/
│   │   └── robots.txt
│   ├── context/
│   │   ├── books.json
│   │   └── movies.json
│   ├── templates/
│   │   ├── base.html
│   │   ├── index.html
│   │   └── about.html
│   └── complexity.yml
└── www/          <---------- output
    ├── index.html
    ├── about/
    │   └── index.html
    ├── css/
    ├── js/
    ├── img/
    └── ico/

Let’s explore some of Complexity’s advanced features.

Config Using complexity.yml

You can configure a Complexity project with a complexity.yml file like this:

# Config file for a Complexity project

# Directories are relative to current (project) dir
templates_dir: "templates"
assets_dir: "assets"
context_dir: "context"
output_dir: "../www"

# List of templates that should not be expanded to pretty-format URLs
 - "404.html"
 - "500.html"

Put complexity.yml in your project root (e.g. in project/).

Here is what you can configure:

  • templates_dir: Directory containing templates. Anything that needs to be templated goes here.
  • assets_dir: Directory containing static assets (to be copied over without templating).
  • context_dir: Directory containing .json files to be turned into context variables for the templates.
  • output_dir: Directory where the generated website will be output.
  • unexpanded_templates: List of HTML templates for which you want to keep the URLs unexpanded (e.g. 404.html instead of 404/index.html).

All of the above are optional.

Complexity uses sensible defaults. If you don’t specify a complexity.yml, this is the assumed default config:

templates_dir: "templates"
assets_dir: "assets"
context_dir: "context"
output_dir: "../www"

JSON Auto-Loading

Data from .json files in your context directory automatically turns into template context data.

For example, suppose you have this in context/books.json:

    "url": "",
    "title": "Two Scoops of Django"
    "url": "",
    "title": "A Very Magical Caterpillar Tale"

Then you can refer to the books in a template like this:

{% extends 'base.html' %}

{% block title %}Index{% endblock %}

{% block content %}
    <p>Here are my books:</p>
    {% for book in books %}
        <a href="{{ book.url }}">{{ book.title }}</a>
    {% endfor %}
{% endblock %}

The contents of books.json get turned into {{ books }}, which in this case is a list that you can iterate over.

What About Static JSON Files?

If you have .json files that you want served as static assets rather than turned into context data, that’s fine.

Just put them in assets/js/ (or anywhere in assets/), and they’ll get copied over to the output directory like any other static asset.

Other Asset Directories and Files

You can create any type of asset directory or file that you want in assets/ (or your desired assets directory).

All assets will get copied over to www/ when you generate your site.


Better handling/processing of assets will be implemented in an upcoming release, including CSS/JS minification, image optimization, and SASS and/or LESS compilation.

Using Complexity as a Library

Complexity can be used just like any other Python package.

You can simply call the Complexity API like this:

from complexity.main import complexity

complexity('project/', 'www/')

Calling other Complexity API functions is just as straightforward:

from complexity import generate

# Optionally generate context if you need to
context = generate_context(context_dir='project/context/')

# Generate HTML from your templates (and context, if you have it)
generate.generate_html(templates_dir='project/templates/', output_dir='www/', context=context)

# Copy assets over
generate.copy_assets(assets_dir='project/assets/', output_dir='www/')

This allows you to use Complexity as a dependency in your own Python projects.


As of this release, the API works, but it is subject to change. Please pin your dependencies if you need this to be stable, and keep an eye on this section for changes when you upgrade.