kiroku 0.8.0

Static blog generator

What is Kiroku?

Kiroku is a tool written in Python for creating and build a fully static blog or web page. That means, no server side language, framework, mod_python/mod_wsgi is needed. To serve such generated content pure web server is more than enough.

Some highlights:

• Almost no external dependencies (only docutils is required)

• Works with Python 3

• Modifiable templates

• Simple search

• Generated RSS channel

• i18n aware

• Configurable via ini file

Kiroku (喜六, in the meaning of putting something into the record; writing something) name was chosen for this project before I realized, that there already are software projects with the same name. Most of them are inactive, so I decided to keep that name.

Requirements

Besides (obviously) Python 3, there is only one dependency - docutils.

For proper date time representation, pytz module is highly recommended, unless you are lucky to live in the Europe/Warsaw or UTC time zones, or you simply don’t care, and stick with local time represented in UTC format.

Last possible dependency is pygments, which automagically enables syntax highlight in code blocks.

Installation

1. Install globally

   root@localhost # pip install kiroku

2. Virtualenv is one option

   user@localhost $ virtualenv-python3.2 blog
   New python executable in py3/bin/python3.2
   Also creating executable in py3/bin/python
   Installing distribute...done.
   Installing pip...done.
   user@localhost $ cd blog
   user@localhost blog $ . bin/activate
   (blog)user@localhost blog $ pip install kiroku

3. Also, it can be download and used directly:

   user@localhost $ git clone https://bitbucket.org/gryf/kiroku.git
   user@localhost $ cd kiroku
   user@localhost kiroku $ PYTHONPATH=/home/user/kiroku python3 scripts/kiroku --help

   Note, that PYTHONPATH should be defined correctly.

Usage

Once installed, kiroku command should be available, and can be used for building the structure of the blog or web side:

user@localhost $ kiroku init blog

This command will create default directory structure, under which several items will be available:

• articles - directory where all articles/posts shall be stored

• .css - contents of this directory will be copied into destination build - directory as css. All modification to the CSS should be done there. File /.css/style.css is the default (and only) CSS file. Note, that during build every file with extension .css will be minified.

• .js - directory with JavaScript files. Will be copied to build/js during build.

• .templates - this directory contains all the templates that Kiroku uses to build the pages.

Now, just change the directory to blog and issue the command build to generate entire site:

user@localhost $ cd blog
user@localhost blog $ kiroku build

Generated HTML files, style, JavaScript files - all of that will be placed in the build directory.

Articles/pages

Every article, which should be taken into considerations should be placed in articles directory. Images should be placed in a subdirectory (images, img, graphics, res are the common choices). Files can be named in any convention, but in two conditions: they must have .rst extension, and they have to be on the root of the articles directory. Kiroku will not scan that directory recursively. Articles can have date prefix, just to have them chronologically sorted, for example 2001-12-17_foo.rst.

There is one special article file which is treated differently - about.rst. It doesn’t have any fields mentioned below; they will not be processed. As the name suggest, this is About me page.

Each page is a simple reST document. There are two modifications, that are implemented in the kiroku module, which make difference from ordinary reST document:

1. More comment.

   If the author place the comment .. more in the article, it will inform the Kiroku, where to cut the page and place the first part (a summary of the article, perhaps) of it on the index page, archive, description fields on RSS and so on. Example:

   Hendrerit sem, eu tempor nisi felis et metus. Etiam gravida sem ut mi.
   
   .. more
   
   Vivamus lacus libero, aliquam eget, iaculis quis, tristique adipiscing,
   diam.  Vivamus nec massa non justo iaculis pellentesque. Aenean accumsan
   elit sit amet nibh feugiat semper.

   That will make only first line to appear on the front page.

   Placing it on the page is not mandatory, so there is no point to do it on short articles, but it is a good idea to put it on the huge articles, since several huge articles on the front page can annoy readers.

   This idea was taken from blogger platform, but I think, that I saw that on other blog platforms too.

2. Special fields

   Fields are special elements, which may (or may not) be present on the document itself, but their role is rather to describe reST document, then make significant appearance on that document itself.

   Kiroku use three fields, which will be utilized to describe an article:

   • :Title: - Field should contain the title of the article. If leaved empty, it will be guessed from the file name.

   • :Datetime: - Creation date. If not provided it will inherit the value from article file creation time. Format, as described on datetime module is as follows:

     "%Y-%m-%d %H:%M:%S"
     # for example:
     "2000-01-24 17:33:31"

   • :Tags: - Comma separated labels for the article. Of course, can be unset.

   All of those fields are optional but it’s highly recommended to have them on the articles. All fields can be lowrcase or upercase - it does not matter.

Article example:

:Title: My article
:datetime: 2000-01-24 17:33:31
:TAGS: Lorem ipsum, blog, cats

A subsection
------------

Phasellus eu quam. Quisque interdum cursus purus. In orci. Maecenas vehicula.
Sed et mauris. Praesent feugiat viverra lacus. Suspendisse pulvinar lacus ut
nunc. Quisque nisi. Suspendisse id risus nec nisi ultrices ornare. Donec eget
tellus. Nullam molestie placerat felis. Aenean facilisis. Nunc erat.

.. more

Another subsection
------------------

Luctus et ultrices posuere cubilia Curae; Morbi urna dui, fermentum quis,
feugiat imperdiet, imperdiet id, sapien. Phasellus auctor nunc. Vivamus eget
augue quis neque vestibulum placerat. Duis placerat. Maecenas accumsan rutrum
lacus. Vestibulum lacinia semper nibh. Aenean diam odio, scelerisque at,
ullamcorper nec, tincidunt dapibus, quam. Duis vel ante nec tortor porta
mollis. Praesent orci. Cras dignissim vulputate metus.

If pygments module is present in the system, syntax highlighting for the code blocks can be enabled. It is enough to put the appropriate language for such block, for example:

.. code:: python

   print("hi")

It will produce:

print("hi")

Configuration

Kiroku provides simple configuration via config.ini file. After the initialization there is an example for the configuration in the file config.ini.example. It can be renamed to the config.ini and then edited.

Following options under [kiroku] section are available:

• locale (default C) - language of the web pages.

• server_name (default localhost) - target server name. It’ll be used for links in RSS and for favicon.

• server_root (default /) - The root of the page/blog can be set here. If set to foo, all the full links will be prefixed with it, i.e. http://localhost/foo/link.html.

• server_protocol (default http) - It may be changed to https

• site_name (default Kiroku) - Site name. It will be displayed at the top of the page.

• site_desc (default Yet another blog) - description of the website/blog. By default only seen on the RSS description tag.

• site_footer (default The footer) - footer of the page.

• timezone (default UTC) - proper name of the time zone the dates should be represent. Without pytz module, there is only Europe/Warsaw and UTC time zones implemented.

Besides configuration, there is possibility to influence the look of the page by simply adjusting the CSS file and the templates, which can be found under .css and .templates directories respectively.

Translations

For now only Polish translation is available. Any help with translation is welcomed :)

Development

For development, virtualenv is strongly recommended. Following dependencies and tools are required. Python packages:

• coverage - tool for code coverage measurement

• slimit - for minifying JavaScript files

Although not necessary, but recommended are two additional packages:

• pep8

• pylint

Which should be used during development.

All Python dependencies can be installed inside virtualenv environment with pip command:

user@localhost $ virtualenv -p python3 kiroku-ve
user@localhost $ cd kiroku-ve
user@localhost kiroku-ve $ . bin/activate
(kiroku-ve)user@localhost kiroku-ve $ pip install -r dev-requirements.txt

Among the mentioned above packages it will also (try to) install docutils and pygments modules.

If there is a plan for creating new message catalogs, or generating them, there will be also GNU gettext needed (tools like xgettext and msgfmt in particular).

Usually, for simple tasks automation I’ve been using Makefile and make utility, or the paver python task manager. However I’ve been trying to decrease external dependencies only to the really necessary modules, so I’ve implemented extra commands to the setup script, so that it can do a bit more than you’ll expect from setup.py :)

The commands are as follows:

• test - execute the tests, and display the code coverage for them,

• minify - minify JavaScript files (for now it is only one),

• genpot - generate .pot file out of the source files. File kiroku.pot will be placed under kiroku/data/locale directory,

• gencat - generate message catalogs for every available source .po files.

Note, that during build, message catalogs will (try to) be regenerated, otherwise the interface will be in English by default, regardless of the language in the config.

test command may have two additional parameters:

• --verbose or -v - will turn on all of the messages printed out by the modules. This could be useful for debugging with pdb.

• --coverage or -c - will measure and print out the code coverage

Every command should be executed in the root directory of the Kiroku repository (the directory where setup.py exists).

TODO

There is still much to do. Here is the list of things I’m planning to do:

1. Module kiroku.naive_tzinfo should be expanded to support more timezones.

   Timezones are needed because of the pubDate tag in RSS and datetime attribute in <time> HTML5 tags. To decrease dependencies I’ve decided to implement a naïve implementation for timezone info object and for now only for CET/CEST timezone. The goal is to make it pytz compatible, so Kiroku can use it if available. Done.

2. Module for comments.

   I’m not decided yet on the way to append comments system (if any). For sure an obvious choice could be adapting the templates to utilize disqus or similar commenting system, use some self-hosted solution (like isso), or even go with moderated (through the email) solutions, as described in Matt Palmer blogpost.

3. Make the templates use some engine like jinja or mako. Initially, I have plan to do that, but eventually I’ve decided to keep Kiroku simple. Maybe, if the interest will be big enough, I’ll add it later.

License

This software is licensed under Simplified BSD License:

 Copyright (c) 2013, Roman Dobosz
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright notice, this
    list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.