Tahchee Manual

AuthorSébastien Pierre
Version0.9.8

Quick setup

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.

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.

Note

You can alternatively install Tahchee by copying the tahchee directory within the Sources directory of Tahchee within your Python site-packages directory, and running tahchee with the following command: python -c "import sys, tahchee.main ; tahchee.main.run(sys.argv[1:])"

First run

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.

How the stuff works

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:

More about templates

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:

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.

Notes

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.

Templates and the build process

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

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

Using Kiwi markup

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

$content
' 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.

Configuration

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.

Extending Tahchee

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

Writing a plugin is very easy:

Some advices

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

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.