rest2web: Building Websites Across the Known Universe

Introduction to rest2web

Creating a Website With rest2web


emoticon:paper Creating a website with rest2web is easy. Looking at the bewildering array of options in the restindex can make it seem very complex. In fact, you can build a simple website in a few minutues - using only a few features. You can then add things as you need them. If you look in the source files for the example site [1], you can see that most of the pages have only two or three items in the restindex.

This tutorial explains the basics of creating a website - and shows you an example.


This tutorial assumes you are basically familiar with HTML and creating/editing text files.

A Basic Site

The principles of rest2web are simple. A rest2web site has at least the following elements :

  1. Config file - this tells rest2web where to read files from (the start directory), and where to put the files it creates (the target directory).
  2. template.txt - This is the HTML template for your website.
  3. index.txt - This is the source file (content) for your main index page. Each directory must have this file.
  4. Optionally other text files for your other pages.
  5. Subdirectories with more content.

We'll briefly look at these things, and then create a basic site.

The Config File

rest2web goes through all the files in your source directory (and subdirectories). It builds the contents, indexes, etc - puts them into the templates, and then saves the results in the target directory.

So at the minimum, rest2web needs to know the source directory and target directory. It gets these from the config file.

You tell rest2web the name of your config file at the command line :

python rest2web.py config_file.ini

If you don't specify a config file, then rest2web will look for one called rest2web.ini in the current directory. On Windoze, this means you can just double click on rest2web.py and it will do it's magic.

There are several other options in the config file- but the source and target directories are the two options you must specify for each site.

Look at the example rest2web.ini that comes with rest2web, or the Config file page, for full details.

The Template File

The template file is the HTML framework for your website. Special values that you put in your template determine where the content, title, and navigation elements go.

The name template.txt is just the default filename. You can change the name and location of this file through the restindex. You can also use more than one template in your website.

If you are only using one template in your website (as many will) then you can do this by just having one file (template.txt) in the top level of your source directory.

The Index File

Every directory must have a file called index.txt in it - or rest2web will ignore it. Smile

Every rest2web page must start with a restindex. This is a set of options that tells rest2web how to build the page.

The index page is important. Some of the options you set in the restindex of your index page apply to the whole directory.

The index page also has some extra information available to it (about the othe pages in the directory). This allows you to have in your index page, links to each of the pages in that directory along with descriptions (including any subdirectories).

Other Pages

In order to be a rest2web source file, a file must be a text file (.txt) and start with a restindex. There are over twenty different options you can set in the restindex - but you will probably only need to use a couple on most pages. Some of these options are only relevant to index pages anyway.

A restindex looks like this :

    format: html
    page-title: This is the Page Title
    crumb: Short Title
        This is a description of the page.
        It can be more than one line long.

Immediately after the restindex comes the page contents. If this is in reST format then docutils will be used to turn it into html.

The page contents is then put into the template - and any special values are converted. This allows for things like sidebars and navigation trails [2] to be added to your site.

After all the files in a directory have been processed, rest2web moves on and processes any subdirectories.


Subdirectories will also get rendered. Each subdirectory should have it's own index page. This index page can be automatically linked to in the index page of their parent directory.

Creating an Example Site

Ok - so let's see how this works in practise. Very Happy


The simple site we create here can be seen in the tutorial_site [3] folder of the docs.

The first thing we'll do is create a config file.

Config File

If you were to create an example site from scratch you would need to create a directory for it all to go in. In this tutorial our source directory will be docs/tutorial_site, and the html will be put in docs_html/tutorial_site.

In our example we won't use any macros, so you can create a text file called rest2web.ini with the following values :

# these values are all left at the default
psyco = True
pause = False
log_file = 'log.txt'
DEBUG = False
compare_directory = ''

# these values we have edited for our site
start_directory = 'docs/tutorial_site'
target_directory = 'docs_html/tutorial_site'
macros = ''

This config file is actually called 'tutorial_site.ini' in the distribution.

HTML Template

The HTML template has the basic framework of our website. We put special values into the template - so that rest2web knows where to put things like the page title, the page content, etc.

A website can use as many different templates as you want - for different parts of the website, or even a different one for each page. Surprised Most websites will only need a single template though.

The full doc page for templating gives you a list of all the special values we can use in our templates. (We can also use these in our page content). Last count there were about twenty five of these values. Like the restindex, we can create our basic site by only using a few of these.

We use these values in two different ways. For single values we surround the values in <% ... %> tags. For chunks of code, we use <# ... #>.

We only need to use special values for things that are different in each page.

We save the template as template.txt and put it in the root directory of our site. Because it doesn't start with a restindex, rest2web won't attempt to process it as a page.

Here's our simple HTML template :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <title><% title %></title>
    <meta http-equiv="Content-Type"
        content="text/html; charset=<% final_encoding %>" />
    <link rel="stylesheet"
        href="<% path_to_root %>stylesheets/rest.css"
        type="text/css" />
    <link rel="stylesheet"
        href="<% path_to_root %>stylesheets/test.css"
        type="text/css" />
    <div id="nav">
            <# print_crumbs(breadcrumbs) #>

    <div id="main>
        <a name="startcontent" id="startcontent"></a>

        <% body %>

        <div id="end">
            <p><a href="#startcontent">Return to Top</a><br />
                Page last modified <strong><% modtime %></strong>.


It's actually XHTML, so it starts with the proper DOCTYPE [4]. The rest is a pretty simple document, with no real content.


We use two stylesheets in the template.

One is test.css, which contains the styles for our page [5].

The other is rest.css, which has the styles for docutils generates HTML.

You can see the special values in the template. Let's look at the ones we have used :

Special Values

  1. <% title %>
  2. <% final_encoding %>
  3. <% path_to_root %>
  4. <# print_crumbs(breadcrumbs) #>
  5. <% body %>
  6. <% modtime %>


<% title %> will be replaced with the title for each page. For index pages, and pages in html format, you must specify the title in the restindex.

For pages in reST format, your top heading becomes the page title.


<% final_encoding %> is the character encoding used for the page. This can vary from page to page or you can set it for the whole site in your main page.

In order to be valid html you must specify an encoding. If you don't know about encodings then rest2web will attempt to work them all out for you - and do the right thing. By default it will output the page using the same encoding as the content.

To learn more about how rest2web handles encodings - read the Text Encodings page.


<% path_to_root %> is the path from the page being created to the root directory (always ending in a / unless the page is in the root directory).

You might be used to specifying the location of stylesheets using the form /stylesheets/styles.css. This gives the absolute location of the stylesheet - but means that the file cannot be viewed correctly from the filesystem.

Using path_to_root for stylesheets and images (etc) puts the correct relative path in - meaning that the site can be viewed from the filesystem.


You can see that <# print_crumbs(breadcrumbs) #> uses the second style of tags - <# ... #>. That's because it's a function call not a value - and we use it's output.

print_crumbs is one of the built in functions. It prints the navigation trails that are known by the weird name breadcrumbs. Tradition puts them at the top of the page.

print_crumbs prints them as a list of items - so we put the function call between unordered list tags <ul> ... </ul>. There are some css rules that cause them to be dispayed properly.


<% body %> is the contents of the page. Razz


<% modtime %> is the date (and time) that the source file was last modified.

The Index Page

When you run rest2web it scans the start directory, processing every text file with a restindex. From each text file it creates a corresponding output HTML file. By default, the filename of the output file will be the same as the source file - except ending in .html instead of .txt. Having completed all the files in a directory, rest2web then does any subdirectories.


rest2web will overwrite files in the target directory, creating all necessary subdirectories.

So by default index.txt in the source directory becomes index.html in the target directory. If you don't want your index page to be called 'index.html' then there are a couple of ways you can affect that. You can either use the target keyword (in the restindex of course) to specify an explicit target name for the target file, or you can use the index-file keyword. 'index-file' tells rest2web that this file isn't the real index page - but another one is instead. rest2web will then read that file and treat it as the index page for the directory. Whichever you choose every directory must have a file called index.txt, with a restindex, or rest2web will ignore that directory.

Our file index.txt starts with a restindex. We're going to make it as simple as possible.

Our index page is going to be a short introduction to the site, and have links to all the other pages, with descriptions of them. For our main index page we'll use HTML rather than reST :

    crumb: Home
    format: html
    page-title: rest2web Tutorial Website

<h1 class="title">rest2web Tutorial Website</h1>
<h2 class="subtitle">An Example Index Page</h2>

<div class="displaybox">

<p>This is the index for the <a href="../site.html">rest2web Tutorial
</a> website. It's not got much on it - other than this paragraph and
links to our other pages.</p>

The page is divided into two parts - the restindex, and the content.

The restindex

Every rest2web source page starts with a restindex. The restindex has sensible defaults, so we only need to include values that we're changing. For details of all the restindex options, read the restindex page.

We are using navigation trails in our template. That means each page should have a crumb. Because this is the index page, we use the traditional value Home.

Our page is html. The default format is html - this is rest2web after all Smile - so we need include the format: html argument.

Because the page is html (and also because it is an index page [6]) it needs a page-title.

And that's all we need in our restindex. Wasn't that easy. Razz

We are relying on lots of default values - we don't define any sections for our directory, we're ging to let rest2web handle all our encodings, and so on. The restindex page will tell you all the default values for the restindex options.

The Content

The content is nice and standard html except, we can see one of our special values turning up again. This time it's a call to one of the standard functions - print_details.

print_details displays a nice list of links to all the pages in a section. Your index page can be divided up into several sections. This enables you to have one directory with pages on several different topics. Each page then has a declaration in the restindex as to which section it is in. (The section keyword in the restindex). You have to declare your list of sections in the index page.

As you can see we haven't done that Laughing - so all the pages in our directory will go into the default section.

You access a lot of data about all the pages in a directory using the sections special value. You can read about that in the templating page (along with all the other special values you can include in your pages).

You access information about the default section through sections[None] or default_section. default_section is just an easier way to access the same information.


sections is a Python object called a dictionary. You access members through their keys. In the sections data structure each member is a section. Each section is also a dictionary. Each section includes a list of all the pages in that section.

section = sections['section-name']
pages = section['pages']

Every directory has all the sections you define in the index page and the default section. This has the key None. You can also access the default section through the special value default_section.

You can use dictionaries to build quite complex data structures. You can learn more about dictionaries in the Python Tutorial or in the Python docs about Mapping Types.

print_details takes an individual section to display all the pages in a section. Any subdirectories in a directory can also be displayed as 'sub-sections'. Because all our pages will be in the default directory we call print_details with the default section - <# print_details(default_section) #>.

Other Pages

Having created an index page, we want to add other pages to our site. Let's create

We've created our main page. The main page acts as an index to all the pages in the directory.

So we need some content. Because this is rest2web, we'll create the page in reST format.

    crumb: A Page
    link-title: An Example Page
        This description is for the index page.
        You can use **reST** markup if you want.

 A ReST Title
 The Subtitle

    This is a comment. To use the 'raw-role', we have to define it

.. role:: raw-html(raw)
    :format: html

This page is written in ReStructured Text markup. That's
why it looks like *plain text*.

This page lives at :raw-html:`<em><% pagepath %></em>` [#]_. This tutorial isn't
a tutorial on ReStructuredText though. If you're looking for one, you
might be better off with the `docutils documentation`_.

.. [#] The file path is dynamically inserted by rest2web.

.. _docutils documentation: http://docutils.sourceforge.net

The restindex for this page is a bit different to the one for the index page. reST is the default markup, so we don't need to declare it explicitly in the restindex. Additionally, docutils will automatically generate a page title for us from the top level heading.

If we don't specify a crumb, the page title will be used. This is too long, so we specify a short one.

We want this page to appear in the index page. It's entry will appear as a link with a brief description. If we don't specify a link title, the page title will be used. Often this will be ok - but here we've specified a different one [7].

So the text used for the link is the link-title value and the text used for the description is the page-description value. This is a multi-line value and can contain reST markup.

reST Content

The content is straightforward reStructuredText. If you want an introduction to ReST, A ReStructuredText Primer is a good place to start.

Notice the use of the raw role : :raw-html:`<em><% pagepath %></em>`. This allows us to insert rest2web special values into the page (without docutils escaping the < symbols). You can only use the raw role if you declare it first.


Directories can have subdirectories. These appear in the index page as 'Subsections'. The subdirectory must have an 'index.txt' file. The 'link-title' and 'page-description' specified here are what appear in the index page of the directory above.

We'll create a subdirectory - imaginatively called 'subdirectory'. We'll create the following file, and save it as 'index.txt' :

    crumb: Subdirectory
    target: subdirectory.html
        A subdirectory - with pages of it's own.

 Subdirectory Index Page
 The Subtitle

.. role:: raw-html(raw)
    :format: html

.. raw:: html

    <div class="indexblock">
        if not default_section['pages']:
            print '<h2>No Pages Yet</h2>'

.. class:: intro

This page lives at :raw-html:`<% pagepath %>`. The ``class``
directive applies a style to this paragraph.

I didn't want this page to be called index.html. I could have used the index-file option to specify another file as being the index page. Instead I stuck with keeping the source file as index.txt, but specifying an alternative target filename. That's the target keyword.

This page is also in rest format. This means that we don't need to specify a format in the restindex.

The content prints an index using print_details - but only if there are any pages. It checks first (if not default_section['pages']:), and if there aren't any it prints the No Pages Yet heading.

It also uses the class directive to apply a class to the paragraph - so that it can be styled with CSS.

More Advanced Topics

In this tutorial we haven't used any macros, or sidebars. Macros allow you to easily insert smilies, python source coloring, and lots more into your pages. The functions to create sidebars are described in the standard functions page. There are many options in the restindex that we haven't explored here - and also lots of special values that we haven't looked at.

Despite what it doesn't show, this tutorial does give you a good overview as to how to create a website using rest2web. For further examples you can look at the source files in the docs folder. These use most of the features of rest2web - and you can see the results in the finished documentation.


[1]In the docs folder of the distribution.
[2]For some bizarre reason known as breadcrumbs.
[3]The only difference is that the main index page has the include: No option set - so that it doesn't go into the main index. Razz
[4]Purists might note that I haven't included the xml declaration. This is because it puts IE into quirks mode.
[5]I've just re-used the main stylesheet for the rest2web docs. This is easier for me - but it means there are a few extra values in there.
[6]Index pages need a page-title in the restindex. This is so that rest2web doesn't have to build the page (for reST content) when examining the index pages of it's subdirectories.
[7]The link title can also be used by sidebars.

Return to Top
Part of the rest2web Docs
Page last modified Thu Mar 30 17:04:24 2006.

Site Built with rest2web SourceForge.net Logo Certified Open Source

Python on Voidspace