Powered by Koishi

Since 2002 I've moved my blog from b2 to Wordpress to my own PHP CMS to Nanoc to Octopress to Jekyll and now to Koishi.

Leaving Jekyll

Jekyll was just the tool I was looking for. I loved how it got out of your way and left you to set things up pretty much exactly how you wanted them but it did how have one flaw; you had to remember how to use it.

For someone like me who writes articles very infrequently this became a little problematic. I'd have to check the docs every time I wanted to add another article which I'll admit wasn't too bad but it did sometimes put me off writing knowing it wasn't quite as easy as putting fingers to keyboard and tapping away.

I wanted to update the styling of my blog one day and found myself climbing back into the docs. It didn't really like the feeling of a barrier between me and the HTML being generated so I decided to get rid of all this fancy stuff and write pure HTML. But first I needed to figure out a good way of doing this.

Back to the 90's?

Many years spent developing websites instinctively told me that because my blog has more than one page there would be part of HTML I'd want to reuse like a header and footer. Now let me see, what was that thing I used to use all those years ago to do this? Ah yes, SSI. So off I went using the very latest technology to rebuild my blog anew.

It was going great. No conventions to worry about, no docs to read and my host still supported SSI. Then it was time to create the obligatory blog post listing page. You know, the one that has a list of blog posts ordered by date. Obviously I'd have to create all this by hand and that's when I started to think that perhaps this wasn't such a good idea after all. On top of that I had no way of changing the page title that was part of my header.html file to the title of the post currently being read which would have made for some pretty odd looking results in search engines.

I started to wonder if I could harness the power of CGI scripts like I had in the past to free me from having to manually write repetitive HTML code but before I started to firmly cement my new blog in 90's tech I started wishing there was a simple way of adding a little dynamic touch to my simple HTML files that was more up-to-date and well-supported across hosting providers like PHP. Yes, I've spent so long creating full scale web apps in PHP that I'd quite forgotten the simpler age when one could drop a snippet of some crap code between ones HTML and get a "snazzy hit counter"™.

Design ideals

When designing Koishi the philosophy was to write as little code as possible (a practice I commonly adhere too). The aim was to create a system so simple that it doesn't really require documentation or any learning (proving you have a basic understanding of how HTML/CSS/PHP of course). This presented some interesting challenges as it's only too temping to write code to "solve" a problem. Avoiding writing code requires some creativity and much of the code I originally started off with was eventually deleted in favour or simpler solutions.

The end result is a method or a way of building a website by using PHP's built-in functions and there isn't much in the way of code as you'll soon see.

Say hello to koishi.php

The following code is essentially all there is. I've written a few plugins that take care of things like listing blog posts but the following is a much as you'd need to build a simple multi-page site.

 * Koishi v1.0 - A minimalist way of building hand-written websites
 * https://github.com/chriskempson/koishi

// Feel free to change any of the settings below to your liking. 
// All paths should be defined with trailing slashes
define ('root', $_SERVER['DOCUMENT_ROOT'] . '/../');
define ('partials', root . 'partials/');
define ('plugins', root . 'plugins/');

// Load all plugin files. Plugins must follow the convention
// PLUGIN_PATH/plugin_folder/plugin.php.
foreach (glob(plugins . '*/plugin.php') as $filename) 
    include $filename;

Koishi has two fundamental concepts. The first is particles; small snippets of HTML that can be reused such as a page header or navigation links. The second is metadata; information that is used to describe an HTML file such as the date an article was written or a title of a page.


As you can see in the code above a path to partials is defined as a constant. Here's an example of a partial that resides in partials/header.php.

<!DOCTYPE html>
    <title><?= $meta['title'] ?></title>

The following example shows how you would use the header.

<?php include partials . 'header.php' ?>


You'll notice that the above code makes use of metadata to populate the title. Here's an about page that lives at public/pages/about/index.php that demonstrates how this works.

<?php include $_SERVER['DOCUMENT_ROOT'] . '/../koishi.php' ?>

<?php $meta = get_meta_tags(__FILE__) ?>

<?php include partials . 'header.php' ?>

<meta name="title" content="About">
<meta name="date" content="2017-04-22">

<p>Some text</p>

<?php include partials . 'footer.php' ?>

First koishi.php (contents listed above) is included. Then we parse the current file for meta tags using get_meta_tags and store the results in a variable called $meta. Next a partial called header.php is included and now has access to variables in the local scope, in this case $meta (you can see its use in the previous code example). Next there is pure HTML and finally a particle called footer is included and the whole page has finished rendering.

Anything else?

As I mentioned there are a few small plugins I wrote that provide helper functions but this is essentially all there is to Koishi. There's really not a lot here and that's what I like about it. I've been using it for around a year now and I've not yet forgotten how to use it.

In case you were wondering, the name means pebble in Japanese. The idea is that Koishi is a small item which can have other small items stacked upon it (plugins) rather like a stack of pebbles but ultimately you'll be left with something small. After all, this isn't something for building large scale websites.