Clockwork Evolution

Programming | Gaming | Electronics | Japanese


Blogging with Jekyll

1 Background

I have been using Jekyll with GitHub pages for quite a while now, although I haven't been so active in terms of actual blogging.

What I like about it is that it's a relatively simple and pure way of writing blogs, without the baggage of heavyweight CMS or blogging software. Essentially you write articles in markdown format, and Jekyll will automatically convert those in to HTML pages. There are simpler methods, of course, like writing in plain HTML, however, with careful setting up of templates, you can also get category and tagging support for Jekyll sites.

I have stripped most other code though, although I currently, at the time of writing, have Google Analytics and Disqus scripts included, although by the time you are reading this, then it's likely that I may have removed Analytics at least. In fact, I may also remove Disqus too, as sometimes feedback can be useful. It seems ironic that, as a professional programmer, and web applcations developer, that I would eschew the technological pizzazz of modern web frameworks. However…

Websites are becoming unusable

In other words, there is too much focus on agressive advertising (the war and counter-war of ads and Ad-Blockers), unnecessary and accessibility-breaking animations and over-engineered / overly complicated layouts. How many times do you start reading a blog or article, and are almost immediately bombarded with ads or, rather ironically, popups asking you to sign up or give feedback. Even worse are those sites that have been given the propensity to automatically play video promotions.

Incidentally, there are other much more insidious methods used quite recently in certain websites which embed bitcoin mining code to secretly use your device's graphics card to generate money while you browse.

2 The Workflow

The workflow is quite simple - I have written a Python script called blog that takes parameters for a category and tags and takes me to Vim, where I can immediately start writing the article in markdown. Once saved, I have another script, serve which starts a local installation of Jekyll and I can review the rendered version. Committing and pushing the changes to the GitHub repository is then all that is needed in order to publish the new content to the site. The content I write will be wrapped in the Jekyll templates, and can look as simple or complicated as you like.

2.1 Workflow Illustrated

  • Create a new blog page with appropriate tags, category and title:
cd ~/project/my-blog.com
blog --tags electronics arduino --category electronics "Binary Clock"
  • Launch the localhost server for Jekyll, accessible on 127.0.0.1:4000
serve
  • Commit changes and push them back to github, where the new blog page will again get processed into HTML
git commit -am "Add article about Binary Clocks"
git push origin

The blog command, in addition to creating a new file for the blog entry itself, it also ensures that appropriate tag and category files exist in the _my_tags and _my_categories folders. Files in these two locations are used by the Jekyll templates to automatically add links between the pages.

It works well, although in the pursuit of automating my life, I would like to make it more of a one-step process…

3 Enter Emacs

In the last few years I have started to use the Linux command line much more intensively, for all kinds of reasons (not least of all i3wm). It is a good feeling to be "close to the metal", and using the command line not only gives you more direct control, it's incredibly fast, will work on any computer, and you can automate anything. I do also love the *nix philosophy "to do only one thing, and do it well", which incidentally is also the overarching tenet of Object Oriented development.

It also should be said that I'm a relatively long-term user of Vim, and now love the key-bindings, especially with my Caps Lock remapped to the Escape key.

So, why would I want to use the monolithic, carpel-tunnel-syndrome-inducing monstrocity that is Emacs?

Well, aside from magit, I can boil it down to two words: Org. Mode.

4 Why is org-mode useful for blog writing

Actually, it's not just blog writing that org-mode is useful for - it's useful for all kinds of things, including personal organisation, documentation, scheduling and task management to name a few.

What makes it of particular interest for me for blogging are:

  • It's very similar to Markdown in format which makes it readable in its vanilla form
  • As it's plain text, it's easy to edit the files, even if you're not using Emacs
  • It supports links, tables, todo items and checklists
  • Standardised formatting

5 What's left to do

Aside from the script, and using Emacs to write the articles, my next phase will be hopefully to add a hook when exporting an org file, to ask for tags and the category and extract the content and title from the template (the latter part is what I now do manually). This could be then placed in to a page in the appropriate place for the blog, ready for reviewing. I also want it to be able to regognise an existing org file I've been working on and update the matching blog page from that.

I also believe that it's possible to have images linked in the document that I could embed into the blog page for uploading.

The end result should mean that I will have org files representing all the pages in the blog, and will be able to add to them or make changes easily, while updating the site.

6 Summary

While there are still some rough edges of my workflow to sort out, I believe that the process works really well. Add to that I have practically zero reliance on any non-free software to write the blog and have full control over all aspects of the cotent, it's much better to work with.

comments powered by Disqus