A quick introduction to Kaa

(updated for version 0.8)

What is Kaa?

Kaa is a weblogging (aka "blogging") tool written in pure Python. It works on the client side; all you need to publish your writings is an FTP account. It also supports client-side scripting, in Python of course.

Disclaimer

Kaa is currently in alpha. Many things may change, although the database layout is pretty stable right now. Future versions of Kaa should have no problems with the current database format. Still, I cannot make any guarantees, so use with some caution.

Requirements

Kaa requires the following:

Installation

There's hardly anything to install... just unpack the archive. Run kaa.py. That's it.

Creating a blog

Select Blog|New... in the menu, and type the id of your blog. This should preferably contain letters, numbers and underscore only (much like a Python identifier). This id will be used to create directories; for example, a blog named "foo" will result in directory names "db_foo" and "html_foo".

This id is not the same as the title of the blog. That, and more, you can edit by selecting Blog|Edit blog info.

Opening a blog

This is done by selecting Blog|Open.... In the little dialog, you type the id of the blog. You can also start Kaa with the id as a command line parameter, e.g.
  kaa.py test
for a blog called "test".

It may be convenient to make a small script or batch file (or a shortcut, in Windows) that calls Kaa with the appropriate blog id.

Writing blog entries

Simply use the large edit boxes in the screen. The narrow one on top is the title of your message, the large one is the message body. The title is not necessarily included in the HTML if you don't want to, but it's used for putting a "name" to messages.

You write your message in pure HTML. (However, some tools may be added in the future to allow for a simple, non-HTML, markup, that will be translated to HTML.) When you're done, press Save to store the entry in the database. At this point, no HTML is generated yet, much less published.
Future releases may also support inclusion of Python code in an entry, by the way.

Existing entries are edited by picking them from the list presented to you by Entry|Edit existing entry.

Templates

To generate HTML pages, you need two templates. These templates are basically HTML, so you can add any custom markup, style sheets, etc. (Kaa doesn't help you with this; it's not a page layout tool.) To include your entries in these templates, you'll need to embed Python code. For example, your page_template.html may look like this:
<!-- template -->
<h1><% blog.title %></h1>
<i><% blog.description %></i>
<hr>
<p>
<% blog.messages() %>
<hr>
Generated by Kaa 
<#
import resource
doc.write(resource.__version__)
#> on <#
import date
print date.Date().isodate()
#>.
All you need is <% blog.messages() %> really, this includes the blog entries; the other code includes Kaa's version number and the current date and time. (Note: This may change in future versions.)

The entry_template.html file may look like this:

<h3><% entry.title %></h3>
<% entry.text %>
<br>
<font face="Tahoma" size="1">Posted on
<% entry.insert_date %>
<#
if entry.modified_date and entry.modified_date != entry.insert_date:
    print "[ Last edited on", entry.modified_date, "]"
#>
</font>
<p>
Again, all you really need is <% entry.text %> and <% entry.title %>, and maybe <% entry.insert_date %> for the date that the entry was posted. The other code adds the modified date in case the entry was changed after it was posted.

So, you use normal HTML, with Python expressions between <% %> and Python statements (or code blocks) between <# #>. For expressions, the value is included. For statements, it works a bit different: anything printed to sys.stdout is included in HTML instead.

Sample templates are included with the Kaa distribution.

Posting and publishing

Currently, the implementation of these features is very rudimentary. More sophisticated options for archiving will be added in future releases.

In Kaa-land, "posting" means generating HTML pages, while "publishing" means uploading these pages to FTP. Posting is done using the templates above; you can set the names of the templates (and also the name of the page being generated) in the "Edit blog info" screen. Select Publishing|Post to create one HTML page with all entries, or Publishing|Post recent to create a page with the 20 most recent entries. Any generated HTML is stored in a directory html_XX where XX is the name/id of your blog.

When publishing, Kaa connects to your FTP account (settings can be edited with Blog|Edit FTP info), and uploads everything in the html_XX directory. (The benefit of this is that it's easy to add additional files, like pictures... just put the files in your directory and they will be uploaded the next time you publish. The drawback is that you can add this way, but not delete. Maybe some future features will deal with this as well.)

Save-post-publish is a three step, but there's also a "One click publishing" button that does all three these things.

Categories

You can associate an entry with one or more (actually, zero or more) categories. To manage categories, use the Blog|Edit categories screen. Note that this isn't perfect yet; deleting categories does not remove them from entries that have them, nor does renaming categories rename them on the messages that have them. This will (should) be added later.

Again, category names should preferably be identifiers.

If you check the "category archives" checkbox in the bloginfo screen, Kaa will generate archives per category (in addition to "regular" archives). It takes the last N entries in a given category and puts them on the page, much like the "front page" works.

That's about it...

...at least for now. Future versions may include all kinds of nifty features. Kaa isn't meant to be the be-all, end-all of blogging tools, though. It's meant to be a humble personal weblogging tool, that can be customized at will, using the power of Python.

For more up-to-date info, and current developments, keep an eye on the Kaa development weblog.

Reactions, comments, bug reports, tips, ideas for features and improvements, etc, are welcome. (Bear in mind that it's heavily under construction, though... "obvious" bugs and lacking basic features are most likely on my to-do list already.) You can contact me here.