rest2web: Building Websites Across the Known Universe

The restindex

Controlling rest2web Through the restindex


reST format alone doesn't tell us everything we need in order to build the pages. It will generate a title from the top headline - but it won't tell us things like which template file to use, what text to use as a description of the page in the index, etc. For this I've added something called a restindex, which is a simple list of keywords and values to go at the start of every page you want rest2web to render for you.

There is another set of values you can add at the start of your files. These are uservalues and they allow you to add your own values into the namespace when templating. See the uservalues page for the details.

The Master restindex

This shows every option in the restindex - with an example value. In practise you only need to ever use values that are different from the defaults. For a good example see the tutorial.

# this is a comment
    include: yes
    format: html
    file-extension: shtml
    template: template.txt
    template-encoding: utf8
    index-file: index.txt
    section:  section name
    link-title: This is the text to use in the link
    page-title: We *usually* only need a title for HTML
        this is a description
        It can go across several line
        And even be indented a bit.
        It will be interpreted as *reST*.
    crumb: Short Name
    build: yes
    tags: keyword1, keyword2, keyword3
    file: filename1
    file: filename2
    file: filename3
    target: thisfile.html
    encoding: utf8
    output-encoding: utf8
    sectionlist: section-name1, section-name2, section-name3
    section-pages: section-name1, page1, page2, page3
    section-title: section-name1, title
    section-description: section-name1
        This is also a description.

    section-pages: , page1, page2, page3
    section-title: , Default Section Title
    # note the leading ',' to specify the default section
        Default section description.


Every rest2web source file must start with a 'restindex' chunk. This tells rest2web how to render the page. If a text file doesn't start with a restindex, it won't be processed.

To qualify as a restindex - the first non-empty line of the file must be restindex. Subsequent lines that start with a '#' are comments.

Each line is in the format - keyword: value, except for multiline values. Currently this means only the description: type keywords.

If a keyword is missing, or the value is blank, then the default will be used.

The restindex is used for two purposes.

  1. For setting values for individual pages. In this case the index is at the start of the page that is being processed. Only certain values are relevant.
  2. In the index page, the restindex can set options for a whole directory.

The Keywords

The keywords are as follows. [1] :

  1. include - include this file in the index ? Should be yes or no. If no, the page is still generated from the template - but not included in the index page.

    This value applies to both normal files and index files.

    Default value is yes.

  2. format: - so far this can either be 'rest' or 'html'. It would be theoretically possible to allow other markup formats like 'sextile', or 'textile'. This is the markup format of the page. If it is 'rest' then docutils is used to generate the html (and usually the page title). The page contents are processed for embedded code, along with the templates (this allows you to use the templating in your indexes, using the .. raw:: directive you can even do this in reST documents).

    The default value for this is 'rest'.

  3. file-extension: - what file extension to use for this file. You don't need to specify the '.'. Normal values would be html, htm, shtml, or shtm. In 'index.txt' it can apply to a whole directory.

    The default value for this is 'html'. (Grr... I'd prefer it to be 'shtml', but there you go).

  4. template: - this is the file to use as the template file. Relative locations will be relative to this directory of course. The template is processed for each page - and the body inserted, title created, dynamic elements are processed etc. See note on Handling Paths.

    In an 'index.txt' this can specify the template file for the whole directory (and directories below it as well).

    The default value for this is 'template.txt'. If none is specified in 'index.txt' and 'template.txt' doesn't exist, then 'template.txt' in the directory above will be tried. (moving up directories until one is found)

  5. template-encoding: - This is the encoding of the specified template file. If an encoding isn't supplied then it will be guessed.

  6. index-file: - this specifies which page to use as the index file. (This file is used as the source to build the index file and as the target to link to in the index for the next level up). If 'index.txt' has this value, then all other values will be read from the restindex of the specified file. See note on Handling Paths.

    It only has any meaning in the 'index.txt'. It can be used to specify an alternative page as being the main index page for this directory. The index page in the next level up will link to the target of the specified file.

    Default value is 'index.txt'.

  7. section: - This specifies what section this page should appear in, in the relevant index page.

    For 'index.txt', the relevant index page is the next level up. The section is the section this index page will appear in, in the index above ! Got it ? (So for the 'root index' this value will never be used).

    The default value is for a page to be in the None section.

  8. link-title: - this is the text used in the link to this page from the index page.

    In an 'index.txt', this will be the link to the index from the next level up.

    The page title will be uased as the default value, if none is specified.

  9. page-title: - this is the page title. You should specify the page-title for index pages and for html pages. If the page body is in rest, this value overrides any autogenerated value.

    In an 'index.txt' this has the same meaning as in ordinary pages.

    There is no default value for this FIXME: could use the filename ?

  10. page-description: - This marks the start of the description, which actually starts on the next line. The description is the text used along with the link to this page. Currently description format is 'rest' only. If you want to include HTML you can always use the 'raw' directive ! The page description can go over several lines - it terminates with '/description' on a newline. Uniform indentation (spaces) that occurs on every line, will be removed before processing.

    In an 'index.txt', this is the description used in the next level up.

    The default value is '' (no description).

  11. crumb: - this is a short name for the page. It will be used for generating the 'breadcrumb' navigation links.

    For index pages, this name will form a link back to the page.

    The default value is to use the page title [2]. (Which will usually be too long).

  12. target: - This specifies the target file. This will be the filename of the 'built' file, and the filename linked to in the index. If this keyword is used, the 'file-extension' keyword is ignored. (So a file extension must be included in the value for this keyword). The target can be a relative path to the file. See note on Handling Paths.

    This value applies equally to 'index.txt' as other files.

    The default value is the filename, minus '.txt', plus the value of the 'file-extension' keyword.

  13. build: - This should be 'yes' or 'no'. This allows you to specify that a file is not to be built, but should be included in the index. This allows you to include prebuilt files in the index. In conjunction with the target keyword, it can be used to link to files in other locations.

    This value applies equally to 'index.txt' as other files.

    The default value is 'yes'.

  14. encoding - this is the encoding of the file. The value must be a recognised python standard encoding.

    This value applies equally to an index file.

    The default value is to ignore encoding and leave the 'subtools' (docutils) to guess encoding.

  15. output-encoding - this is the encoding the page is written out as. The output-encoding ought to match the encoding used for the template ! The value must be a recognised python standard encoding, or one of two special values. unicode means don't encode the page - but present it to the template as a unicode string. None means use the encoding the page was originally encoded with.

    This value applies equally to an index file. Setting it in an index file will set this value as the default for the whole directory and any subdirectories. (Unless an alternative is explicitly specified).

    The default value is 'None', which encodes the page using the encoding the page was originally encoded with. If a value is specified in any of the index pages above this page, then that will be used instead of the default.


    Not including this keyword is not the same as including the keyword with no value.

    Not including it will cause the default for this directory to be used.

    Including it, but leaving it empty is the same as specifying None.

  16. sectionlist: - This is a list of different sections for an index page. Links to pages in this directory appear in these different sections. The names should be unique as they will be used as "id's" to reference the section in the index.

    This value only has meaning in an index page.

    The default value is to have a single section referenced as 'default' if it isn't named.

  17. section-title: - This is how you specify the title for each section. The first value is the nameof the section, followed by the title to be used for the section. This can be made into a link back up to a section table at the top of the index page. You can have multiple section titles, one per section.

    This value only has meaning in an index page.

    The default value is to use the section name as the title. (In 'Title-Case').

  18. section-pages - This specifies the order that pages appear in the section, for example in sidebars and in the sections data structure (used by the print_details standard function).

    The first value is the section name (or a leading comma for the default section). You use the filename (minus the '.txt') to specify a page. You don't have to list all the pages - but including a page that doesn't exist will raise an error. The pages you specify will appear in that order, followed by the rest of the pages in an arbitrary order.

    If you want to specify a subdirectory then use the directory name followed by 'index'. For example - subdirectory/index.

    This value only has meaning in an index page.

    The default value is for pages to be in an arbitrary order.

  19. section-description: - This is a description used for this section. It will appear above the links to the pages in the section. Other details are the same as the page-description.

    This value only has meaning in an index page.

    The default value is '' (no description).

  20. tags - This option takes a list of keywords that applies to the page. You can then use this list in your template and pages. (E.g. for the meta type="keywords" data).

    This value applies equally to an index file.

    The default value is for it to be an empty list.

  21. file - This option specifies an additonal file to copy from the source directory to the same directory as the target file. You can use this keyword multiple times in the restindex.

    This value applies equally to an index file.

    The default is for no additional files to be copied.

  22. plugins - A list of plugins that should be applied to the page. See the plugins page for more details.

Building the Index

The contents of a directory will only be built if it has an 'index.txt' file. This doesn't mean that the main file needs to be called 'index.html' or similar. There are two ways of changing this.

First - the 'index.txt' file can contain the content, but have a target value set. This sets the filename that the built file will be saved as.

Alternatively, 'index.txt' can have an index-file value. This will specify an alternative file that is to be used as the index page. In this case all the other values in 'index.txt' will be ignored and the values from the specified file will be used. This means the restindex will be very short :

    index-file: anotherfile.txt

Handling Paths

Windows, Linux, and the Mac, all handle paths differently. rest2web uses the file structure on disk to represent the structure of the website [3]. This means we are using the same relative file paths to represent the file path on the local computer (on which rest2web is running) and the links within the website. Because the different OS's represent filepaths differently - we have a conflict between specifing file paths and urls.

A few of the restindex keywords expect a path. Specifically template, index-file, and target. template is always a filepath - because it specifies a file which is built into other pages. This means it can be specified as an absolute location - or using a native, relative file path.

For the other two values, index-file and target, rest2web expects the path to be a relative path, that follows the Unix path conventions. This greatly simplifies our path handling routines.


You may be using rest2web to only generate some of the pages in your website. In this case it can be useful to provide a restindex for pages that rest2web isn't building. This enables rest2web to include them in indexes etc. You can easily doing this by setting the build: No option in the restindex. If you have several pages like this in a directory it can be a nuisance to maintain all the files for them. rest2web allows you to put several restindexes in a file called 'restindex.txt'. See the Special Files page for more details.

As a summary - every restindex in 'restindex.txt' will be assumed to have build: No set, but you must specify a target - or all the ouput files will be named 'restindex.html' Bad Grin


[1]If you see # by every entry in this list (in the output html) rather than a numbered list, you need to update your version of docutils. (0.3.8 or more recent required)
[2]For index pages we may not pick up on the default of using the title - this is because we don't generate the page when reading the defaults. Index pages need crumbs !
[3]Although you can override this using the 'target' keyword.

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