Moving to Jekyll

    • jekyll
    • outcoldman
    • blog
  • modified:
  • reading: 5 minutes

I finally did it. I found some time to get rid of my old custom-made ASP.NET blog and move all my content to static web site powered by Jekyll. If I remember it right this is my third move. I started my blogging “career” at GotDotNet (it was old-Russian-only blog/forums website about .NET development). After some time I decided that I want to have my own place with only my blog posts and so I started to write on LiveJournal. Not the best choice, so after some time I built my own webblog powered with ASP.NET 2.0 which I used until yesterday. It worked really well for these 4 years, but it was too old and a little bit ugly.

I was looking on the various options where I can go next. Of course I could continue to support my own custom made blog, I could add Markdown and fix some CSS/HTML. And to be honest I actually already did that partially.

While I was doing that I made decision that it should store all my content as simple markdown/html, so I will not need to use any Databases and simplify deployment of new entries in my blog. Also I wanted to be able to run it under Linux/Windows/MacOS (Mono also works). This is where I decided that I actually need to take a look around to find out what people are using in .NET/Node.js worlds (this is where I am right now). This is where I found that even .NET guy from GitHub Phil Haack (I guess the only one .NET guy in this company) is using Jekyll. More than that his web site is open sourced under MIT License, so you can use it as a tutorial to build your own Jekyll-based web site (or even fork it). And so I decided to try Jekyll as well.

I also spent some time trying to find some good node.js alternatives. There are a lot of them, like docpad, wintersmith or hexo, they are all good, but in summary they have less forks than Jekyll. This means a lot.

There are couple of things I’ve learned while I was doing all that Jekyll + Disqus. If you are going to do the same soon - it can be useful for you as well.

Jekyll and GitHub pages

  • Jekyll is very easy to setup. Install it with gem using Quick-start guide. Don’t try to install github-pages - I don’t see why you may need it, and it is not so easy to install because of some dependencies on native libraries.
  • If you are going to host your blog on GitHub pages - start exploring Jekyll plugins form the list of officially supported by GitHub plugins. I started my learning from Jekyll’s Plugins page and ended up with AliasGenerator which is not supported by GitHub. Not a big issue, because I still can commit all of the auto generated by AliasGenerator pages (this is the beauty of static websites).
  • All of the projects on GitHub get default entries in pattern like, except one which is named like, it will be hosted under root of Not having virtual paths in web-site root helps you to have absolute urls like /.


Disqus is the worst of the best. I mean you cannot find better service for commentaries, but this one does not support Markdown and custom themes. I even tried to build my own on NodeKnockout (I believe demo site does not work anymore), but just did not have a time to complete it after.

There are some things which can help you with importing your old commentaries to Disqus:

  • If you have your own format of commentaries you can prepare them with special XML format which Disqus understands.
  • I did not know that you can upload at first the list of all threads you already have. So I ended up with executing JavaScript which opens all existing pages, so they will force Disqus to create thread for each of them.
  • If you have IDs in commentaries and you specify them in wp:comment_id - don’t afraid to upload the same commentary more than once. Disqus smart enough to match them, so you will not have duplicates.
  • Cyrillic is a pain. Disqus stores URLs in encoded form, so if you are using special symbols or non-ASCII characters you will get something like %D0%BA%D0%BE%D0%B2%D0%B0%D1%80%D0%BD%D1%8B%D0%B8%CC%86 instead of Коварный in URL. It can be a pain, because some characters can be encoded differently by different frameworks/languages. For example Russian character й can be encoded like character й (%D0%B9) or with и (%D0%B8) and one of the Combining character %CC%86. Just be aware about that.

Attribution to open source

  • Having Phil Haack’s open sourced blog was very helpful. Also I used it as an inspiration for my own design. As you can see it is the same design, but completely different CSS. I also decided to keep my theme under MIT license.
  • Bower - the easiest way to keep all the client references up to date.
  • HighlightJS - best of the best for source code highlighting.
  • normalize-css - I verified how my site looks only in Chrome and Safari. Hope that because of normalize.css it should look the same in all other browsers.
  • font-awesome - the best set of icons you can get on the web.
  • Jekyll and jekyll_alias_generator.
  • Open Sans font - good combination with Georgia.
  • Grunt - JavaScript task runner.

See Also