Published:

Jarle Aase

First attempt: Jekyll

bookmark 5 min read

My background in web technology

I was first introduced to the key concepts of documents with embedded links to other documents, on a huge scale, by my boss, many many years ago. He was a visionary IT leader at the regional hospital at a wet spot up in the Cold North. I was the new PC technician during the days and a passionate QNX hacker in the nights. This was years before Berners-Lee invented the World Wide Web in 1989.

In 1996, I got a ISDN Internet connection at home, and decided to make my own homepage. The first version was hand-coded in HTML. It was nothing special, but it was bothersome to add new content. So I wrote a Windows application, HTMgen32 in C++ with MFC to do the dirty work. It was among the very first GUI programs to generate a website from "pages" of content, via templates, to a static website with navigation bars, menus etc. Microsoft launched it's FrontPage 2000 suite, with many of the same ideas in 2000.

Some years later I implemented a support system to manage my free software projects in php/mysql/apache. It had many of the same features as an early version of Source Forge (downloads, tickets, users logins, version tracking etc.)

Later on, I wrote a content management system (CMS) in php/mysql/apache and migrated my websites over to it. It was also used by a handful of companies in Norway for a decade. To handle larger numbers of user sessions without caching (we wanted to generate the content of all the pages for all request to get page counters and comments correct), I moved most of the page generation over to a server written in C++, and accessed it from a C module in php.

In between larger projects, I have written Apache, nginx and IIS modules to enhance the functionality or tighten up the security for my customers.

I have also written a handful of HTTP servers over the years. From simple ones, meant for embedding in applications (like a SNMP browser, or a FTP Server User Interface), to vUbercool a monolithic beast written in C++ that can host 50% of the sites on the Internet on my aging Thinkpad w520 laptop.

In 2016, I wrote a high performance C++ REST client library.

Web technologies are not alien to me.

A new blog

In order to just publish some thoughts, without friction from missing features in my aging CMS system, I started looking at today's options. And wow. Numerous they are!.

Drupal

I first tried to install Drupal on a Linode server. I have some friends who are very enthusiastic about it.

It was not trivial to install. When I was done, the standard layout was - well - not compelling. I looked for themes, and it turned out to be a mess with themes bound to specific versions of Drupal, lot's of abadoned themes, and few ones that actually supports mobile devices out of the box. Since most readers today use their phones as the reading device, I think it's a good idea to have a website that handles that. After reading a few chapters of a book about Drupal, without getting much further, I gave up.

Note to self: Whatever software I create - make it easy to install, and easy to understand!

Wordpress

Too many security issues all the time. It may be fine for mammy bloggers and cat people, but not for anything security related or controversial. That will attract people who despite the idea of other peoples Freedom of Speech (like the notorious idiots at "Anonymous" who believe ddos is a rhetoric asset).

I want to write and ignite ideas - not spend most of my nights restoring my site from backup.

Ghost

This hosted platform actually looked perfect. Professional blog hosting for writers. Then I looked at their Terms of Service, and was kindly reminded why I have avoided hosted services in the past.

"Ghost Foundation may terminate your access to all or any part of the Website at any time, with or without cause, with or without notice, effective immediately."

Get lost!

Back to static pages

To my amusement, there is a movement away from Web 2.0 "dynamic" web applications, and back to good, old static pages. I can understand that, as it is very very hard to manage the complexity of a modern "micro-service" based web application, based on hundreds or thousands of libraries and projects of which the developer of the interactive web application has zero control. How do you secure such a beast? Well, it seems like most people just don't. So back to static pages!

Jekyll

I will not list all the static web side generators I evaluated. I ended up trying Jekyll.

It installs a lot of crap, even some native programs/libraries that needs compilation. I installed it in a VM, but it is available in Debian, so it's probably safe to run on a workstation.

The default layout is very simple. But it worked out of the box on all devices I tried it, without requiring JavaScript. That was nice - actually two of my primary requirements for any publishing platform. It also handles syntax highlighting of C++ source code. Since I plan to write about C++ - that matters.

What I don't like about Jekyll is that it does not properly separate content from formatting. It keeps everything under one directory, and it seems like different themes have different expectations regarding the structure. Not good. Worse is that many (all?) themes basically invades the directories with their own versions of both logic and formatting files (templates, css, special html pages etc), making it hard or impossible to experiment with different themes. You basically select a theme, and then stick with it, and apply your own changes directly in the themes own files - effectively forking the theme. That's not good if you want to change or upgrade your chosen theme at a later time.

I also bumped into some nasty behavior when I started to write my first, own post. It did not show up at all in the default theme. It turned out there was a error in a special section at the start of the page, where the posts name, date, author etc. are declared. Jekyll silently dismissed my content. That's bad. It makes it hard for people to understand how to proceed. It took me a few minutes to pinpoint the reason. But I'm a professional software developer - I know how coders think and what kind of errors they are likely to make.

When I installed a theme, I ran into a more serious problem. The theme installed some 3rd party modules that trashed the whole installation. After that, Jekyll would not work with any theme.

$ jekyll s
Configuration file: /home/jgaa/blog/testetest/_config.yml
            Source: /home/jgaa/blog/testetest
       Destination: /home/jgaa/blog/testetest/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
     Build Warning: Layout 'post' requested in _posts/2017-01-23-welcome-to-jekyll.markdown does not exist.
  Liquid Exception: Included file '_includes/icon-github.html' not found in about.md
jekyll 3.1.6 | Error:  Included file '_includes/icon-github.html' not found

It turned out to be a problem where some binaries were in /usr/bin (Debian) and some in /usr/local/bin (installed by the theme when it was deployed) - and they were not compatible. Zapping the theme - and the files in /usr/local/bin fixed the problem. Again - I am a professional with long experience hunting down such problems. Don't expect a Mummy blogger with a Cat getting pass such an obstacle.

Currently I am using Jekyll with it's default theme for this blog. I have just added one item to the css file to enable the weird viking up in the left corner.

Update: October, 2017

There are many things to like about Jekyll. However, the things I did not like eventually stopped me from blogging actively. So this month, I sat down with some notes about my dream blog-generator and wrote it in C++.

I call it stbl, an acronym for "Static Blog Generator".