rest2web: Building Websites Across the Known Universe

rest2web - The Site Builder

Autogenerating Websites with Docutils

Author: Michael Foord Cool
Contact: fuzzyman@voidspace.org.uk
Version: 0.4.1
Date: 2006/02/01
Home Page:rest2web
Quick Download:rest2web-0.4.1.zip
Sourceforge:rest2web Project Page
Development:SVN Repository
Support:rest2web Mailing List
Site Built with rest2web
Building with rest2web


  • Introduction to rest2web

    A gentle introduction to rest2web.

  • Configuring

    The rest2web config file.

  • Tutorial

    An tutorial showing how to use rest2web to create a simple website.

  • Templates

    A description of templating, and the special values available in the namespace.

  • The restindex

    An explanation of the options and default values in the restindex.

  • The Standard Functions

    The standard functions for printing indexes, navigation trails, and sidebars.

  • Macros in rest2web

    The text macro system used by rest2web. Includes documentation on all the example macros.

  • Special Files

    A list of all the special filenames that rest2web uses - and what they are for.

Sub Sections

  • Reference Section

    Documentation and reference for rest2web.

  • Test and Example Site

    This website tests all the features of rest2web. If it builds correctly then all is well. It also serves as an illustration of rest2web, including some of the more obscure options and capabilities.

  • Translation Example

    A very basic example of a website with multiple translations.

  • Example Gallery

    Example gallery from the gallery plugin. (Only present if you build it).

What is rest2web ?

emoticon:python rest2web is a tool for autogenerating wesites, or parts of websites. It's main features are :

  • Integrated with docutils.
  • Automatically builds index pages and navigation links (sidebars and breadcrumbs).
  • Embedded code in templates for unlimited expressiveness.
  • Flexible macro system.
  • Uses relative links, so sites can be viewed from the filesystem.
  • Unicode internally - so you don't have to be. Razz
  • Includes features for multiple translations of sites.
  • Built-in gallery creator plugin.
  • The basic system is very easy to use.
  • Lots of powerful (optional) features.

The content can be stored as HTML, or in ReST format; in which case the HTML will be generated using docutils. rest2web inserts each page into a template, and automatically creates index pages for sections, and navigation links. Smile

ReST is a WYSIWYG text markup format. It is simpler than HTML - but very flexible. A document marked up with reST is still readable as text. This means that maintaining article contents in reST is a lot easier than maintaining them in HTML.

Adding new pages is as easy as dropping a text file into the right folder. rest2web builds the new page and adds a link to it in the index (optionally with a description as well). Removing a page is just as easy. Delete the file, and when you run rest2web again it removes the entry.

rest2web includes standard functions to build a sidebar, with links to the other pages in the directory, or to the other sections in the website.

Another advantage is that a website can be easily restyled by only changing template files. It is likely that only a few template files will be needed for most websites [1].

Because rest2web generates sites using relative paths, the results can be viewed from the filesystem. This means that it is an effective way of bundling documentation.


With uservalues you can use rest2web to create versions of a website in different languages. Simply create the framework once with your uservalues as place markers - then create your files with different translations. rest2web will build the website and can handle linking the sites together.

An example of a site that uses this feature is, the Website of Marius Soutier.

Static Versus Dynamic

emoticon:html rest2web is a dynamic website generation tool - that generates static (HTML) pages. The rationale of creating static content, is that most pages will only change occasionally - serving static HTML content is quicker than generating pages dynamically. Not only that, but static content can be served by a lot cheaper hosting account!

Distributing HTML documentation is another reason for wanting static pages.

Why rest2web ?

rest2web comes about from a need for me to restyle a whole website from badly marked up HTML 4, into beautiful XHTML and CSS. Very Happy See the Voidspace Manifesto for a discussion of my aims and objectives in the restyle.

An added challenge is that part of the website is already restyled - and the blog pages are built using a different tool (Firedrop2, which also uses ReST incidentally). All this means that rest2web needs to be able to handle generating just part of a website, and indexes for the existing parts where necessary.


rest2web uses a directory structure to represent sites. Each directory can have an index page autobuilt with a link to each page and a brief description.

Each page can (optionally) have a sidebar with links to the other pages in the directory. rest2web will also handle creating breadcrumbs, which are navigation trails to the directories above the one the user is in.

The pages in each directory can be grouped into sections for the index page. The index can have a brief description for each section included automatically.

You can control the order that sections appear on the index, and also the order of pages within each section.

Although rest2web uses a directory structure to represent your site, you aren't forced to keep your contents in this structure. You can put placeholders in the directory pointing to the real location of the file. rest2web will handle making sure that the breadcrumbs, sidebars and index page links all point to the right location.

All links within the site are kept relative. This is especially useful when creating HTML documents that might be viewed from the filesystem.


rest2web is being used to create websites for various Open Source projects and personal websites. Browsing these can give you an idea of the sort of things it's possible to do with rest2web.

The sites I've discovered include :

I also use it to build the docs for :


[1]Many websites will only need a single template file.

Return to Top
Part of the rest2web Docs
Page last modified Sat Apr 01 13:15:47 2006.

Site Built with rest2web SourceForge.net Logo Certified Open Source

Python on Voidspace