How I Made This Blog

2020-04-25 4 minute read

  1. Forked this repository. 1
  2. Named the repository to zkiss.github.io.
  3. The site was then available at https://zkiss.github.io.
  4. Customised the site contents as needed
    1. Changed _config.yml and _pages/about.md
    2. Created blog posts under _posts.

Requirements

I couldn’t just start blogging on Medium.

  • I want direct access to the post data
  • I like writing in a markup language more, than using a WYSIWYG editor
  • It would have been too simple :) - No, seriously. I have written exactly one blog article on Medium and based on that experience I know that it lacks some features I would often use, mostly related to preformatted text (code blocks).
  • I however really liked the clean look of Medium.

Besides the points above, I wanted the solution I end up using to be:

  • Free/very cheap.
  • Easy to maintain.
  • Possible to host behind a custom domain.

Choosing the Stack

As an engineer, I have worked with tools that generate nice static websites based on content written in simple markup. I knew the technology exists, but the tools I have used are more suited for writing technical documentation than personal websites or blogs. I then came across Jekyll which is made for this kind of stuff.

There are many services with a free tier that allow hosting static websites: Netlify, GitLab Pages, and of course GitHub Pages. I have picked GitHub Pages, since I am already a GitHub user.

It is possible to create a statically generated website on GitHub Pages in a few simple steps, described right there on the landing page. All you need to do after that is edit markdown files, and they automatically get published by GitHub as soon as you push them to your git repository. Extended syntax for markdown is supported.

Pretty neat.

OK, Now What?

So far so good, this was the easy bit. What is not explained in detail is how to actually use Jekyll. You do not get a ready-to-use blog engine out of the box either.

So I needed to understand what Jekyll actually does and what it does not do before being able to write posts. How does the Hello World static website I’ve just created turn into a blog? What mechanism do I use to list my blog posts on the main page? How can I make it all look pretty?

Themes

The simple answer to all these questions is themes.

Themes are not simply skins. They are the blog engine. They contain significant functionality. They normally have their own documentation on how to use them. The good thing is, you only need to go through it once, after that you just have to write the blog posts.

The theme I ended up using at the time of writing is Minimal Mistakes (MM). It was a very close call, I almost picked Beautiful Jekyll (BJ) instead. I prefer the design of BJ, but MM seems to have a lot more features, and I think it is a better piece of engineering; you have to fork the BJ repository in order to use it, while MM is ready to be used as a published module.

In practice this means that:

  1. With MM, the blog repository contains only the essentials: your content (blog posts and other pages you want on your site). This is what a clean design for reusability looks like.

    With BJ, you have a full copy of its entire codebase. This makes it difficult for you as a user to know what you need to change when you want to finetune something to your taste.

  2. Updating to a newer version is simple: just update the version number of MM in your config.

    It is harder to update BJ to a later version because you have to perform a merge between your codebase and the codebase of BJ.

I also contemplated building my own blog engine based on the minimal theme that is promoted on the GitHub Pages theme selector, but I decided I am not a graphic designer after all, and I would much prefer spending the time on actual writing instead.

On a sidenote, I want to mention that a lot of the themes suffer from a common problem, when used on GitHub Pages as a ‘project page’, rather than as a ‘user page’.

This is caused by the fact that base paths for project pages are not the root domain, but they contain the project name as well in the path (https://user.github.io/project). This makes absolute urls point to the wrong path when deployed as a project page. More on this subject here. I have decided to host my blog as a user page.

Testing

Once I had the site set up, I started migrating an old post I wrote. In order to test that formatting and links work the way I intend them to, I had to push the changes frequently to git, publishing the post before it was done, and check the resulting post on github pages. I don’t like that, of course, so I looked into how I can test my posts before publishing.

Turns out there is a docker image for jekyll that is pretty easy to use. With that it is possible to build the site locally and check how it looks like. It supports auto-reloading changes from the disk, so you can have it running in the background while working on a post and reload the page when you are ready to check.

All you need to do is run the following command in the git repo root:

export JEKYLL_VERSION=3.8
docker run --rm \
  --volume="$PWD:/srv/jekyll" \
  --volume="$PWD/vendor:/usr/local/bundle" \
  --publish 4000:4000 \
  -it jekyll/jekyll:$JEKYLL_VERSION \
  jekyll serve --drafts

The site will be available on http://localhost:4000.

  1. I did not actually fork, just copied the files I needed. ↩

You May Also Enjoy

Autonomous AI Developer

2023-04-22 33 minute read

This is an AI-generated post

So I thought I’d try something new and ask AutoGPT to develop a simple application to manage todo lists. What could go wrong, right? Well, let me tell you, the AI turned out to be a complete disaster. Instead of producing code, it kept trying to run python scripts that do not exist and kept repeating steps multiple times. Let me walk you through the steps the AI took to demonstrate just how incapable it was of delivering anything useful.

Docker: Cannot Modify File on Host

2020-05-02 3 minute read

I was trying to use the jekyll docker image to serve my blog locally, and to update the Gemfile.lock file.

When trying to serve the blog I got:

$ docker run --rm \
  --volume="$PWD:/srv/jekyll" \
  --volume="$PWD/vendor:/usr/local/bundle" \
  --publish 4000:4000 \
  -it jekyll/jekyll:$JEKYLL_VERSION \
  jekyll serve --drafts

[...jekyll boot, etc...]

jekyll 3.8.5 | Error:  Permission denied @ dir_s_mkdir - /srv/jekyll/_site

Embracing DDD at FOODit: An Eric Evans Workshop

2016-05-31 9 minute read

This post was originally published here on 2016-05-31.

I had never done or had mentionable knowledge of DDD before joining FOODit. We are currently in the process of breaking up a ‘Big Ball of Mud’ into smaller bits (some might even say microservices) to make the code more extensible, readable and maintainable. In the process of doing so we are trying hard to apply Domain Driven Design principles.