Building a Blog using Jekyll

Many developers and designers have chosen to use Jekyll, a static-page generator, for some of their web-based projects for its ease of use and simple design. In this post, we will be building a minimal blog with the help of Jekyll. In an upcoming post, I’ll discuss hosting a jekyll-based blog on Github through Github Pages. This post is intended to be read by programming beginners who want to build and host a blog “the hacker way”. Since we are building this blog “the hacker way”, this tutorial expects basic command-line experience.

What is Jekyll

Jekyll is an open-source static page generator written in ruby, which can be used to build blogs, documentation, and other types of communication tools. Some features of Jekyll include:

  • text-based configuration
  • liquid templating for custom layouts
  • a plugin system
  • a cli tool

To see a full set of features Jekyll offers check out the project home page.

Getting Started with Jekyll

To get started with Jekyll, you will need ruby installed on your machine. To check if ruby is installed on your machine, run the following command in your CLI program:

ruby -v

If ruby was not found on your machine, you can find installation notes here.

Next, let’s install jekyll and bundler, a ruby gem for managing ruby project dependencies. Run the following command to install these gems:

gem install bundler jekyll

Generating a Blog

So far we have setup ruby and installed jekyll, next we will generate our blog. To generate the blog, run the following command:

jekyll new my-first-blog

You’ll see that a new directory called my-first-blog has been created and inside the directory contains some markdown and yaml files and a new directory called _posts. Jump into the newly created directory, by running the following command:

cd my-first-blog

Next, we’ll start up the blogging generation process by running the command:

Quick Note

We’ll be running bundle before each of our jekyll commands, which is the “de-facto” rubygem dependency manager for the jekyll project. To learn more about bundler check out the following link.

bundle exec jekyll serve

After a few moments, you should see a newly created folder called _site. Now, head over to your browser and type http://localhost:4000 and press enter. You should be seeing a boilerplate-filled web page such as the one below ↓.

localhost-screenshot

Editing the Blog

When your blog was created using jekyll new my-new-blog, the following files and folders were created:

  • _posts -> folder containing your blog posts.
  • _config.yml -> file for configuring project settings and global variables.
  • index.markdown -> your index file which relies on a home layout.
  • about.markdown -> another markdown file which we can ignore for now.
  • Gemfile -> file for describing your rubygems dependencies.
  • Gemfile.lock -> file for version controlling your rubygems dependency tree.
  • 404.html -> no explanation necessary.

When your blog was generated using bundle exec jekyll serve, a _site folder was created. Each time your blog is built, this _site folder will be regenerated with your latest changes to your blog. A common workflow when making changes to your blog is the ability to “watch” for changes.

Run the following command to watch for changes as your editing your blog:

bundle exec jekyll serve -w

To see new changes to your blog, just change anything contained in _posts folder and your pages (such as index.markdown and about.markdown).

Writing new Blog Posts

While the bundle exec jekyll serve -w command is running in the background, create a new file in _posts called 2018-11-24-my-new-blog-post.markdown. Run the following command to create the new blog post:

touch _posts/2018-11-24-my-new-blog-post.markdown

Next, jump into your favorite editor (mine happens to be vim when I’m trying things out) to start editing this file. For Jekyll to understand our blog-post we’ll need to give it some attributes the file’s “header”. Let’s start with the following attributes to describe our new post content.

---
layout: post
title:  "My New Blog Post!"
date:   2018-11-24 00:00:00
---

Next, save the file and look at the output of your terminal window running the jekyll serve -w command. You should be seeing a newly added blog post called my-new-blog-post. Refreshing your browser should show your new blog post, however there is no content to view. That’s because we need to write the rest of our blog post!

Quick Note

Before making any more changes to your new blog post, checkout the _site/jekyll folder to see that your new blog post has been generated and placed here. This _site/jekyll folder layout can be changed by updating your site configuration file _config.yml (permalink).

To continue writing your blog post, begin by writing beneath the last trip dashes and save. Check out your changes in the browser, edit, save, and repeat! For more information on the Markdown system supported by Jekyll, check out the following link.

Conclusion

There is still much to explore in what Jekyll offers. I left out some features worth discussing such as Theming and Site Configuration because Jekyll’s documentation is just good enough. I hope you were able to start off blogging “like a hacker” with this short Jekyll tutorial.

If you happened to catch any missing or incorrect details in the post, please drop me an email. And as always, thank you for reading and I hope you catch my next blog post soon!