At first, you will need a Unix-based machine, or a Windows machine with an available shell (using MinGW or Cygwin), with Python 2.4+ installed.

• Download Tahchee, and decompress the tarball
• Ensure that Cheetah (starting from version 0.9.7) is installed
• Optionally install the Python Imaging Library (PIL)
• Optionally install HTML tidy

Once this preliminary setup is done, go into the uncompressed Tahchee directory and do

python setup.py install

You now have the tahchee command available in your path, and should be ready to start using Tahchee.

To test your installation, go into Tahchee Documentation/Example directory and type make. The process should run, and output lines similar to those lines:

[ ] Mode is 'local', generating in 'Site/Local'
[ ] Precompiling template 'Example/Templates/Base'
[ ] Precompiling template 'Example/Templates/Page'
[ ] Generating file 'index.html'

This process will create the example HTML site in the Site/Local subdirectory. You will find the resulting HTML there. If you want to know what other options are available, type make info.

Tahchee is best described as a "website compiler". You design your site with templates, which contain the common parts between all your pages in your website. Once you wrote your templates, you can start writing pages which “fill in the blanks” of your templates. The main difference between a template and a page is that a template needs the data provided by a page to render to an HTML (or whatever format) file. In other words, templates are incomplete pages, and pages complete templates.

To get a better idea of this, let's look at the example data:

|-- Pages
|   |-- index.html.tmpl
|   `-- screen.css
|-- Site
|-- Templates
|   |-- Base.tmpl
|   `-- Page.tmpl

Running make will populate your website project directory:

|-- Pages
|   |-- index.html.tmpl
|   `-- screen.css
|-- Site
|   `-- Local                 (this is the directory created by tahchee)
|       |-- index.html
|       `-- screen.css
|-- Templates
|   |-- Base.py               (these are 'compiled' versions of your templates)
|   |-- Base.tmpl
|   |-- Page.py
|   |-- Page.tmpl
|   |-- __init__.py

We see that the Site/Local was populated with the same content as the Pages directory, excepted files ending in .tmpl were stripped of their extension. Before being stripped of their extensions, the .tmpl files were actually processed with Tahchee to generate the resulting file (which can be HTML, or any other file, such as CSS, PHP, etc).

There are also some .py files in the Templates directory, which are the result of Cheetah compiling the templates files (.tmpl) in the Templates directory into executable Python code.

Tahchee works as follows:

• Compiles the tmpl files in the Templates directory
• Compiles the tmpl files in the Pages directory and copies them in the Site/Local subdirectory, stripping them of the tmpl extension
• Copies other files from 'Pages' to the appropriate location in the Site/Local directory.

You can learn the basics of using templates simply by looking at the files in the example. You will see that in our example, we have a template hierarchy:

Base
`-- Page
    `-- index.html

This means that a change in Base will affect Page as well as 'index.html`. By making new templates that "extend" other templates, you can build a whole set of specific templates for your site sections:

Base
`-- Page
    `-- SectionPage
        |-- FAQPage
        |-- UserPage
        `-- ProjectPage

If you look closer at the provided templates, you will see that some variables (like $site) are already available. Tahchee actually provides access to Python object representing the current page and the website as a whole, using the following keywords:

• $page refers to the current page, and is a Page object
• $site refers to the current site, and is a Site object

The Page and Site objects are defined in the Tahchee Python API, available with this documentation (see Documentation/tahchee-api.html). For instance, the 'site' object provides a link method that allows to link to a path or URL, and ensure that the link target exists.

Since Tahchee 0.9.7 a plugin system allows to make additional variables available to templates. This allows you to write your custom Python class and functions, and easily bind them to your templates.

Templates are "applied" (which means that they generate a file in the Site directory) under a set of conditions:

• They are not filtered out (see ACCEPT and IGNORE in site configuration)
• The template or its parents were modified
• The template was flagged with ALWAYS_REBUILD
• A file state in a DEPENDS directive has changed

If you want a template to be always applied, you should simply add the following line to the top of your template:

## ALWAYS_REBUILD
#extends Templates.Page
...

If you want to state an explicit dependency between your template and another file, simply put its absolute path or path from the template parent directory as follows:

## DEPENDS = ../../path/to/my/file.data
#extends Templates.Page
...

These indications will allow Tahchee to decide when something should be rebuilt or not. In case you would like to do that from the Makefile, you can invoke the build.py script directly with the page you want to rebuild:

python build.py Pages/index.html.tmpl

Since version 0.9.7, "Tahchee" comes integrated with the Kiwi markup language. Kiwi is a simple, expressive text markup language that allows to create XML/HTML documents without actually writing all the HTML tag. For instance

Here is a paragraph, followed by a list:

1) The list is numbered
2) Here is the second item
   - Here is an unnumbered sublist
3) And the third item

generates the following HTML code:

<p>Here is a paragraph, followed by a list:</p>
<ul>
    <li>The l ist is numbered </li>
    <li>Here is the second item
        <ul><li>Here is an unnumbered sublist</li></ul>
    </li>
    <li>And the third item</li>
</ul>

Kiwi comes pre-installed with tahchee. To use it, simply process any of your variable with the $kiwi' function. For instance, if your page template contains a content section

' that holds your page content, and that you expect `$content' to contain Kiwi text, simply use the following:

<div id="content">$kiwi($content)</div>

This will enable any content to be written in Kiwi. Also, note that with kiwi you can mix HTML (or XML) with Kiwi without any problem, so you can gradually convert your HTML files to Kiwi markup if you need to.

Kiwi is pretty much similar to Markdown, but maybe more powerful in some areas. You can learn more about Kiwi here.

Tahchee can be configured to meet your specific site setup. All the configuration should be made in the build.py file in your Tahchee website directory, which present you the available options.

Your website build.py contains a set of options that you can change and edit. These options should look like the following.

# You can change the following things
# =============================================================================
URL     = "www.ivy.fr/tahchee"
INDEXES = ["index.*"]
IGNORES = [".cvs", ".CVS", ".svn", ".DS_Store"]
ACCEPTS = []
# =============================================================================

There are many configuration options available. Here is the complete list of supported options.

• URL allows you to set the main URL from which your website will be accessed. This is useful when you want to generate a website with absolute links.
• MAIN indicates the relative path of the main HTML file for your website. This is usually index.html. When SHOW MAIN is set, then the main file will be displayed in your browser after each build. (new in 0.9.8)
• SHOW MAIN (can be True or False), indicate if you want your main page to be shown in your browser after each build. (new in 0.9.8)
• INDEXES is a set of "globs" (shell-like patterns) that tell which files should be considered as indexes. This also affects link expansion.
• IGNORES specifies a list of "globs" of files that should be ignored. These files will not be copied or processed. You can also give paths relative to the Pages directory.
• ACCEPTS specifies the list of "globs" that will be processed. You should leave this empty, as if you specify one "ACCEPT", then everything not accepted will be ignored.
• TIDY indicates the path to the HTML tidy utility (it is auto-detected otherwise).
• USETIDY_ (takes yes or no, yes is the default), indicates if HTML tidy should be enabled or not.
• TIDYFLAGS specifies the flags that should be passed to HTML tidy. You can also use an environment variable with the same name.
• TIDYCONF specifies the configuration file that should be used by HTML tidy. You can also use an environment variable with the same name.
• CHANGE can be set to date to detect changes based on the file date and sig to detect changes based on the signature.

Tahchee can be very easily extended using its plugin system (since Tahchee 0.9.7).

Writing a plugin is very easy:

• Write your Python code independently
• Wrap your classes/functions into a plugin that will make particular objects available to templates as variables (pretty much like the $site object)
• Publish your plugins by putting them within the Plugins directory
• Type tahchee plugins to make sure that your plugin was registered

Tahchee can be very powerful, provided you do things with a little bit of discipline. Here is what I would advice :

• Spend some time thinking about your site map, and the type of pages that you want to have.
• Do not write too many Templates, try to keep them minimal, and make a list of the variables names that will be filled by Pages.
• Do not hesitate to use templates for your CSS files, as it can allow (among other things) to quickly change a set of predefined colors.
• Cheetah templates allow to use any Python module, so do not hesitate to add extra functionality in Python modules that you can put just inside your 'Templates' directory or anywhere in your PYTHONPATH.
• Do not hesitate to write Plugins to provide custom functionalities (automatic generation of pages or linked data)

I hope this small documentation will help you kickstart using Tahchee, if you have questions or comments, you can contact me at sebastien@ivy.fr.