Setting up the structure and creating source filesΒΆ

Let’s create a new directory that will contain our site: the source files, assets (images, Javascript, CSS, etc.) and a Soho configuration file.

$ mkdir site1
$ cd site1
$ export SITE_ROOT=`pwd`

The last command is just a way to get an “anchor” to the root of your site structure. It is not used by Soho at all but may prove useful in the rest of this tutorial.

We need a directory for the source files. By default, Soho looks for a directory named src so that is what we will use here.

$ mkdir src
$ cd src

We can already create our first source file there named index.rst, with the following content:

This is the **home** page. Look, here is a `link`_ to the second page.

.. _link: second.html

As you can see, there is a link to another file here, called second.html, which we can create with the following content:

  You have reached the second page. Wouldn't you like to go back to
  the <a href="index.html">home page</a>?

Now that we have our content, we need a template. By default, templates are looked up in a templates directory next to the src directory (that we already have).

$ mkdir templates
$ ls
src    templates
$ cd templates

We are going to create our first template named in this new templates directory. We will start with a very simple template indeed:

<div class="content" tal:content="structure body"/>
<div class="footer">Generated by Soho.</div>

We are using Page Templates (also known as Zope Page Templates or ZPT). As you can notice, the only binding here is named body and contain the HTML fragment that has been generated from our source files. We will see later that we can pass additional bindings.

This is enough for a first test. We just need to add a configuration file next to the src and templates directory, which we will name The configuration file is a regular Python file:

asset_dir = None
locale_dir = None
template = ''

Here we need to disable some default values that correspond to features that will be covered later. Let’s check our files before running Soho for the first time:

$ ls
src     templates

We are ready to run:

$ soho-build
<date> - INFO - Building HTML files...
<date> - INFO - Processing "/path/to/site1/src/index.rst" (writing in "/path/to/site1/www/index.html").
<date> - INFO - Processing "/path/to/site1/src/second.html" (writing in "/path/to/site1/www/second.html").
<date> - INFO - Generating Sitemap...
<date> - INFO - Done.
$ ls www
index.html   second.html     sitemap.xml

As you can see, our source files have been transformed to HTML, the template has been applied, and the resulting web site has been saved in files in a new www directory. Also, Soho generated a Sitemap.


If you look closely at the generated sitemap.xml, you may see that the URLs all have some kind of default prefix ( You may change this prefix by setting the base_url variable in the configuration file (if you do so, be sure to run soho-build with the --force command-line option).

You may continue with the tutorial by following the Adding assets section.