Introduction

An sssgen project is a directory tree of four kinds of files:
The interesting work in an sssgen project is done in .mako files. For example, the source to to this page is available at tutorial/index.html.mako.
Every .mako template gets two variables: page and tree.

The page variable

Here is the content of page for this file: 
{   'layout': '/tmp/tmp.wcTMjXadTS/default.html.mako_layout',
    'title': 'Introduction to sssgen',
    'url': 'index.html'}
If you look at the source for this page, you'll see that the keys title and layout were taken from the so-called "front matter" of the file. The front matter is just YAML placed at the beginning of the file, delimited by ---. Front matter is one of four sources for the contents of the page variable:
page is defined as inherited YAML + layout YAML + front matter YAML + intrinsic YAML. Each N+1th source of page keys overrides the Nth source.
The first source of keys in the page variable is inherited YAML. Inherited YAML is the collected of YAML as constructed by walking down the directory to your file, aggregating _inherit.yaml files along the way. We don't use inherited YAML in this tutorial but it's very useful.
The next source of page keys is the chain of layouts. Each .mako_layout file may contain front matter, which is merged into page.
Then comes front matter YAML.
The final source of keys is intrinsic YAML. The url key is provided by sssgen itself. It gives you the URL for this file, relative to the root of the project.

The tree variable

Here is the content of tree for this file: 
{   'css': {   'default.css': {   'url': 'css/default.css'},
               'reset.css': {   'url': 'css/reset.css'}},
    'index.html': {   'layout': '/tmp/tmp.wcTMjXadTS/default.html.mako_layout',
                      'title': 'Introduction to sssgen',
                      'url': 'index.html'},
    'textfiles': {   'spongebob.txt': {   'url': 'textfiles/spongebob.txt'},
                     'squidward.txt': {   'url': 'textfiles/squidward.txt'}}}
tree reflects the directory tree of the project. The leaves are the page variable for a given file. tree is useful, for example, for listing sub-contents. In the following block of code, we use the tree variable and the intrinsic YAML key url that we discussed earlier, to list Spongebob characters:
<ul> Here are my favorite Spongebob Squarepants characters: % for name_of_file, yaml in tree['textfiles'].items(): <li><a href="${yaml['url']}">${name_of_file}</a></li> % endfor </ul>