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 have written 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 a subset of the example data (I've omitted some files which are not relevant in our explanation):

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

Running make will populate your website project directory:

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

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.

Starting from Tahchee 0.9.8, you can use extensions like .tmpl.html as well, instead of html.tmpl. This will make it easier for some editors to get the proper syntax highlighting.

This is however only available to Pages. General templates (those in Templates) have to stay as .tmpl. There are syntax coloring modes for Cheetah templates available in many text editors.

## ALWAYS_REBUILD
#extends Templates.Page
...

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

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

<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 may be more powerful in some areas. You can learn more about Kiwi here.

In addition to Kiwi markup, Tahchee also supports Rest markup. To use Rest markup in one of your templates, simply do:

   $rest("some rest **text**")

if you prefer, you can also refer to a variable defined elsewhere:

#def rest_text
Hello, I am a rest text
#end

and do:

$rest($rest_text)

In case you have encoding problems, the rest function takes the following paramaters:

rest(text,encoding,outputEncoding)

So you can specify the input encoding (encoding) and output encoding (outputEncoding), which should be given as a strings (like utf-8, latin-1, 'ascii', etc)

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).

• USE_TIDY (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

If you don't want to write plugins, you can alternatively drop some Python modules within the Sources directory of your Tahchee website (you have to create this directory, which is not created by default). Tahchee will then automatically add this directory to the Python path.

So, if you create a module in Sources/mymodule.py, you can use it in your page templates by doing:

#import mymodule

and then

$mymodule.doSomething()...

This is probably the easies way to extend Tahchee functionality.

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.