As a developer, I come across technical challenges on a daily basis. Some are complex, but many of them are simple to implement once you take the initial time to figure out how things work. A while ago, I decided it would be a good idea to start writing down the solutions to this type of problems, not only to make my life easier when I encounter them again, but also to help people facing the same problems learn from my mistakes. That’s how this blog was born.

Requirements

Having thought about starting a blog for a while, I had a very specific set of requirements in mind. Some of the more important ones are:

Being a developer, my blog is going to be primarily about code. As such, the ability to post code with proper syntax highlighting is crucial. Highlighting should support at least Java, JavaScript, Bash, Python, JSON, XML, HTML, and CSS. Both native code and embedded GitHub gists should be supported.

The ability to organize posts in a certain way is necessary. I imagine my posts listed on the main page based on their date, and there should be an option to assign a category as well as a set of tags. Tags are used as keywords for posts, and you should be able to list the posts associated with a certain tag. Categories are used to organize posts into series, and there should be an option to list series and view their posts.

There should be an option to store posts in a draft state until they are published publicly. I want to be able to keep my files in version control for backup, and not necessarily write my posts in a single sitting.

Readers should be allowed to express their opinions and add comments to posts. As the author, I want to receive notifacations for comments made on my posts to ensure I can reply to them properly.

I want the readers to be able to subscribe to my posts and I don’t want to have to roll out my custom solution. RSS is a must.

I don’t want my site to get lost in the clutter of one of the many sites for personal blogs like Blog.com or Wordpress.com. I have nothing against those sites, they’re great for what they are for, but I want mine to be memorable and sharable through my own domain. I’ve already owned mirocupak.com anyway, it’s time to put it to use.

It’s 2016. Internet should be safe and HTTPS (HTTP with TLS) should be used everywhere. You might argue that HTTPS is unnecessary for a static website, such as this blog, since the site doesn’t receive any POST requests or handle any sensitive transactions, but that’s not really a reason not to take advantage of authentication, data integrity, and encryption provided by TLS. If for nothing else, you should at least use HTTPS to make your blog easy to find, which is especially important when using a custom domain.

I want to share content, and I don’t want to have to pay for it. I own the domain I want to use, but even if I didn’t, it would be the one thing I would be willing to spend money on. I don’t want to pay for hosting, SSL certificates, licenses, or anything like that. Ideally, the technologies should be open-source.

I want my content to be available globally and I want someone else to take care of this. I don’t want to maintain a server or a database, even if it’s just an instance in a public cloud. I don’t want to take care of monitoring or backups. It’s a blog. It’s supposed to contain static content, provided trough a hosted service.

I’m used to using Git on a daily basis. I like using it even for personal projects I’m not collaborating on with anyone, such all my theses, for the purpose of backups, as well as being able to easily trace and revert changes. I want a solution that integrates well with Git.

The blog should be fun to write, not only with respect to its content, but also with respect to the technologies used. This is especialy important when it comes to markup. I don’t want to write HTML by hand. I prefer text-to-HTML conversion tools, and I especially like Markdown and AsciiDoc.

While I prefer to take advantage of templates to do the heavy lifting, I don’t want my site to be simply a factory copy of someone else’s work. I want to be able to create my own style for my blog. The functionality, as well as the general look and feel, should be easy to customize.

To truly enjoy producing content, local development has to be nice and easy. I want to use a mature framework with support for automatic, easy, and fast builds. The overall quality of related tooling is important.

I don’t want to be vendor locked. The site should be built using standard tools that are not fixed to a particular hosting solution. It should be easy to migrate, if needed.

Technologies

The requirements above narrow down the selection of technologies to very few. The ones chosen for this blog, which collectively satisfy all the requirements above, are listed here:

Static site generator

Choice: Jekyll.

Jekyll is an open-source blog-aware parsing engine capable of generating static sites. It uses Liquid templating language and handles a variety of markup systems. Markdown is supported out of the box, but there are plugins for many other converters, such as AsciiDoc or Textile.

I chose Jekyll because of its efficiency, minimalistic nature and the size of its ecosystem. Although it certainly is one of the well-known and more mature site genarators, there are many alternatives one could opt for. Some of the more popular ones are Gitbook, Hugo, and Pelican.

Syntax and converter

Choice: Markdown.

Markdown is a plain-text formatting syntax combined with a Perl tool responsible for converting the plain-text formatting to HTML. I chose it primarily because I like the format and I’m familiar with it from its use on GitHub and their wiki. I bet that anybody who has used old-school wiki systems like MediaWiki appreciates how big of an improvement Markdown really is.

Examples of good alternatives to Markdown, which are suitable for a blog and supported by Jekyll, would include AsciiDoc and reStructuredText.

Blog toolkit

Choice: Octopress.

Octopress is an open-source toolkit for writing and deploying Jekyll blogs. It’s minimalistic – in fact, it repositioned itself from a fairly heavyweight and hard-to-manage blogging system in version 1/2 to a lightweight Jekyll plugin in version 3.

So what exactly does Octopress bring to the table? Very little, in fact. You could easily create a blog without it and you probably wouldn’t even miss it. Jekyll deals with blogs well enough on its own. It’s just that extra layer of convenience. You install it as a gem and in version 3.0.11, it provides exactly 10 commands – initialization, setting up a new Jekyll blog, creating a new page/post/draft, publishing/unpublishing a draft, stashing and restoring the posts, and deploying the blog to Amazon S3, Git, or via Rsync. Octopress comes with a bunch of plugins, but those are mostly useful if you’re building something from scratch. If you’re starting with an existing theme, odds are it already provides everything the plugins could do and more.

A major drawback of the system is its lack of documentation, particularly for the latest version. Despite the simplicity of the framework, the lack of documentation makes it rather hard to set up. For example, the main website is vastly out of date and describes mostly version 2 of Octopress, which is more or less completely different from version 3.

If you don’t want to commit to Octopress, but feel like you need something extra on top of your site generator, Hexo and HubPress.io are certainly worth checking out.

Build system

Choice: Gulp.

Gulp is a powerful open-source build system popular in JavaScript projects based on various frameworks. It automates traditionally very tedious tasks, such as Sass to CSS conversation, minification of CSS and JavaScript, image optimization, static webserver setup, browser synchronization via Browsersync, and more. Its streaming nature (node streams) combined with a large plugin ecosystem (over 2500 plugins, as of July 2016) make it a very versatile and convenient tool.

Although Jekyll comes with its own build system capable of rebuilding the site when files change (provided via Jekyll Watch, included out of the box since Jekyll 2.1), I wrapped it in Gulp anyway, as it is more convenient, flexible, and I am familiar with it from other projects. If you’re not a fan of Gulp, but you want better automation than what Jekyll provides, the obvious alternative is Grunt.

Hosting

Choice: GitLab.

GitLab is an open-source project for management of Git repositories and code collaboration. It’s also available as a hosted service, which makes it a good alternative to GitHub. In fact, it’s commonly known as GitHub for enterprise. Although the ecosystem of third-party tools is smaller than the one for GitHub, it essentially offers everything GitHub does and more. This includes Pages, free hosting for static websites with support for static site generators.

The main reason I chose GitLab Pages over GitHub Pages for this blog is the ability to connect a custom domain with TLS. GitHub allows you to provide your pages through a custom domain as well, and recently started supporting HTTPS on github.io, it does not, however, support TLS on custom domains. The unlimited number of free private repositories on GitLab is a bonus – although I opensource almost everything behind this blog, I like the ability to version drafts of posts while keeping them private.

If you don’t insist on completely free hosting, Amazon S3 is also a fantastic and very affordable option.

Certificate authority

Choice: Let’s Encrypt.

Let’s Encrypt is a free, automated, and open certificate authority built on top of the Automatic Certificate Management Environment (ACME) specification. Despite the fact that it currently does not support wildcard certificates and certificates are only valid for 90 days, its open nature and ease of setup make it an easy choice for this blog.

Although Let’s Encrypt is unique, free certificates are nothing new. If you’re hosting your blog on Amazon S3, AWS Certificate Manager gives you free wildcard certificates. If you’re not running on AWS, you can obtain a free certicate without wildcard suppport from authorities like StartCom. Speaking from experience, however, be prepared for a very unfriendly user interface, bad customer support, fees for additional services like certificate revocation, and, last, but not least, unavailability of the root certificate in standard environments like Oracle JDK.

Discussions

Choice: Disqus.

Disqus is a platform providing a mature comment system with sophisticated administration options, which can be easily plugged into a web. I knew Disqus from multiple sites I visit regularly, and the simplicity of configuration as well as a rich feature set made it an easy choice for this blog. The flexibility of administration setup and the ability of users to manage their comments in a central location is a nice added benefit.

If you’re looking for something lighter than Disqus, consider checking out some of its alternatives – Isso, ReadBoard, or IntenseDebate.

So here it is – my perfect technology stack for a free developer-friendly blog, powered by open source.