1.Quick setup
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.
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:])"
2.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
.
3.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 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 theTemplates
directory - Compiles the
tmpl
files in thePages
directory and copies them in theSite/Local
subdirectory, stripping them of thetmpl
extension - Copies other files from
Pages
to the appropriate location in theSite/Local
directory.
4.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:
$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.
4.1.Templates and the build process
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
andIGNORE
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
5.Plugins
6.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
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 may be more powerful in some areas. You can learn more about Kiwi here.
7.ReStructuredText Markup
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)
8.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.
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 usuallyindex.html
. WhenSHOW_MAIN
is set, then the main file will be displayed in your browser after each build. (new in 0.9.8)
SHOW_MAIN
(can beTrue
orFalse
), 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 thePages
directory.
ACCEPTS
specifies the list of "globs" that will be processed. You should leave this empty, as if you specify oneACCEPT
, then everything not accepted will be ignored.
TIDY
indicates the path to the HTML tidy utility (it is auto-detected otherwise).
USE_TIDY
(takesyes
orno
, 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 todate
to detect changes based on the file date andsig
to detect changes based on the signature.
9.Extending Tahchee
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.
10.Some advices
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.