Jekyll The Late Intro

The What

The web started as a place for serving static content - some text here, an image there. Then as humans do, we got bored with static stuff; we wanted to change. We wanted to be able to generate dynamic content, to have websites that are alive. This, of course, makes sense and without it, we would have to write individual pages for a lot of pages, and I mean a LOT.

Static site generators promise blazing-fast websites as long as your content allows. To test if you can use one, just answer the following with yes: do you know most of your content at build time or not? Excluding Next.js (because they market themselves as server-side rending and just because I can), and using Github stars as means of rating, Jekyll (Ruby) is the 3rd most used static site generator strongly contenting for the 2nd place Hugo (Go) both being very close to the first spot holder Gatsby (React). You wouldn't need any advanced knowledge of their languages/frameworks unless you intend to customize your instance heavily.

All of the three languages/frameworks were enticing; I've already been looking for an excuse to learn React, been hearing a lot of great things about Go and Ruby has been on my to-do list for far too long now. All three have an excellent ecosystem (plugins/extensions) and community (forums and traction). My first post illustrates the robust scientific methods I used to make my pick. Spoiler: for no particular reason.

The Prep

First, you will need to set up your dev environment. At the time of writing, a working installation of Ruby version >= 2.4.0 is the minimum. Make sure you are ready by checking the versions for both Ruby ruby -v and Gem gem -v. Install bundle while you are at it gem install bundle. Now you are ready for Jekyll gem install jekyll. Create your first blog jekyll new myfirstblog. cd into the new directory created by jekyll and run bundle install to fetch the needed dependencies and finally jekyll serve to run the development server. Open your browser at localhost:4000 and checkout your first Jekyll site.

The Base Structure

Assuming Jekyll version 4.00 with the bundled default minima theme version 2.5.1, you will be presented with the following structure.

• _config.yml
• Gemfile
• _posts
• index.markdown
• _site

A common theme with all modern frameworks (and Jekyll is no exception) is that they tend to follow a sensible-default-by-omission approach; i.e. Unless you specifically override a configuration or add a specific file with specific content, a sensible default will kick in. So expect a bit more directories/files to get added if you want to have full control (read a more customized) over your Jekyll blog.

_config.yml & Gemfile

As the name of the first implies here live the global configuration of your site. Consider this your base properties file (my fellow Spring/Java fans). The latter is how you tell Ruby that you need a particular ruby package (aptly called gem) and with a specific version (that's pom.xml in java/maven speak). Changes to the config file are not picked up by the development server (remember your jekyll serve?) and require a restart to take effect. Furthermore changes to the Gemfile need not only a restart after but also a bundle install to fetch the updated gems.

_posts

Here is where your blog posts live. One file per post each following a simple filename template of YYYY-MM-DD-whatever_name.markdown. Each file needs to start with what is known as Front Matter; a bunch of YAML at the start of a file enclosed between two lines of three dashes each. This is also a recurring theme with Jekyll; the use of Front Matter to convey metadata about the current file to Jekyll. For posts, this contains info such as the post title, the exact timestamp, the tags and categories under which the current post should be filed, the excerpt, and can be extended with additional plugins to include many many more options.

index.markdown

This is what will become the home page of your blog. Minima by default will append the list of blog posts after any content you add to this file, so keep that in mind while adding content here.

_site

This is where the results of the jekyll build results. I hate to tell you what to do but you should NEVER change the contents of this folder; it is generated dynamically and your changes will be overwritten if another build is triggered. Disclaimer: I haven't found any case where you should change this but who knows, perhaps there exist some advanced use cases that call for this.

What follows

In the following blog post, we will see how to start writing these posts.