First, let me explain the unusual name. It is the condensed form of Kagerato Static Site Generator. Essentially, this is a Python program for automating the creation of a website composed of plain HTML files. We may contrast this with methods of dynamically generating a site on-demand using server-side processing.
Why would you want to build a website made of static files? There are two key reasons. One, to dramatically reduce the load on the web server or greatly improve throughput (pages served). Flat data is typically served at a far better rate than dynamic pages. Two, for simple sites it is easier and more maintainable to keep all the content neatly separated into its own files, separate from any database. By using the filesystem alone as the data store, editing content is a mere matter of opening your favorite text editor.
There are disadvantages, as with everything. For one, complicated site features such as user profiles, forums, shops, and so forth are not implementable with this process. However, if desired they can be independently built, configured, and installed to a separate section of the site. One other large disadvantage is that manually authoring HTML is a painful and error-prone process.
That is where site generation tools like kastasigen come in. By putting an intermediate tool in between you and the final site, it becomes possible to write your site in a much more author-friendly text format. There are quite a few of these formats in existence now; some of my favorites are listed in the references section. Kastasigen is designed to be abstract enough to work with many of these structured plain text document types.
There are a few things you will need set up to use kastasigen. One is obviously a Python interpreter. Version 2.6 or 2.7 of Python should work; Python 3 probably will not. Second, you will need a processing tool for your input text format of choice. This is the program which does the backend work of translating your authored text to HTML. Most suitable formats already have such a program available for them; some have several. Finally, you will need the Jinja2 template library for Python installed in an accessible place. This Python library provides the glue which allows post-processed HTML from the translation program to be seamlessly inserted into a syntactically valid HTML file, along with any relevant metadata.
By design, kastasigen's behavior is controlled through an INI config file.
(The initialization format was chosen for its simplicity, plus the fact
that Python's standard library provides a built-in parser.) The default
behavior is to search for a file named
kssg.ini in the current working
directory, but this can be overridden in two different ways. To select
a different file, either specify one on the invocation of kastasigen, or
set the environment variable
KSSG_CONFIG to the desired file path.
As to the structure of the config file, it is relatively straightforward.
There should be one section for each distinct phase of processing that
needs to be done. These sections are read, interpreted, and executed
independently. However, if they share common variables, you may move
those declarations into a section literally named
shared to avoid
having to repeat the values.
Keep in mind that with the one exception of the shared section, the names of the sections for each phase you specify are arbitrary and ignored. Call them whatever you like. Only one phase and thus one section is strictly required.
The various program inputs are fed in through these sections, and so understanding how to write the config file is mainly a matter of comprehending what the available variables do. That will be explained in the next section.
This section is incomplete.
Once the configuration is set up correctly, the rest is easy. Simply invoke the run script with the relevant config file specified and the rest happens automatically.
This code is currently released under these licenses:
Choose one and only one for your usage.
I am considering an additional license, most probably either BSD or LGPL, but have not yet made a decision on that.
The most recent public version is 0.3.1, released on May 9th, 2012. Provided here is a bzip2 compressed tarball of the code.