kzimmermann-site/README.md

A blogging engine implemented in just CGI scripts

This repo contains the code for the http:// kzimmermann.nerdpol.ovh website's engine, powered by just CGI scripts and commonly found UNIX utilities.

The motivation behind it is similar to that found in MyWiki, where simplicity and ease of deployment are the number one goals in development, resulting in an application that can be put up and running within only an hour.

Because of its simplicity and reliance on local administration, kzimmermann-site is perfect for self-hosters. Everything is right where you can reach.

Features and upcoming stuff

• A platform for publishing content locally (remote publishing and its extra security overhead go against the development principle)
• Dynamic generation of RSS feeds.
• Publishing of standard, permanent, non-blog pages.
• Markdown support.
• Search feature on article database (content and title only)
• Templating engine: make your favorite HTML+CSS design elsewhere and then simply plug in the content!

Future stuff:

• Self-hosted comment system (disqus sucks, but then there is trolling...)
• Draft-saving, and versioning features
• Compatibility with other database engines, for those who wish to scale it up.

Send me your suggestions as well!

Server requirements

To be deployed successfully, kzimmermann-site needs the following utilities to be available:

• A web server (tested on lighttpd, should work regardless with Apache or nginx)
• bash shell (not tested with other 'bash-compatitble' shells, thus the recommendation)
• sqlite3
• Optionally, a Markdown-compatible parser if you wish to publish with it.

Setup instructions

First, configure your server to allow the execution of CGI scripts. Because this task is vendor-specific, and usually very well documented elsewhere, I will not go into detail. After that, copy the file structure to the web server root and use the ./site_admin.sh init command to create the database and adjust permissions.

kzimmermann-site now allows you to use any template of your liking to publish your posts into. It comes with a standard, basic template.html file, but you can change it completely to taste as long as you keep the following tokens anywhere within your template:

• {{title}}, which will be substituted by the title of your posts.
• {{content}}, which will be substituted by the content of your posts.
• {{date}}, which will be substituted by the date in which your post was last edited.

Take a look into the template.html file for more information.

From now on, to publish something run ./site_admin.sh post command. You will be asked for a title, and then vim will open for you to start writing your post. The publishing happens automatically, there's no way of saving drafts currently.

Markdown and other formatting engines

To enable Markdown support, you must have a parser available somewhere in your server already. I've included John Gruber's original parser with the distribution, but any other compatible parser should work, so take your pick.

In the index.cgi file, change the markdown="" variable to the absolute path to the parser and you're done. From now on, Markdown posts will be rendered into correct HTML. Notice that on the absence of a Markdown parser, kzimmermann-site will fall back to a simple parser that detects blank lines and creates paragraphs.

Technically speaking, any other formatting engine (like remarkable, etc) should work, but I haven't tested any. As long as the syntax of their executable is the same as Gruber's Markdown.pl, then the integration is seamless.

RSS

For the RSS feed (/feed.rss), simply execute the ./feed_generator program locally. You can automate it by scheduling a cron job to do it.