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. This post is intended to be read by programming beginners who want to build a blog “the hacker way”.
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:
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:
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 ↓.
Editing the Blog
When your blog was created with 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 - file containing Not Found content.
When your blog was generated, 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:
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.