I recently decided to start a blog. I had used Wordpress in the past, so I knew I could get my blog up and running quickly using Wordpress. I was also slightly familiar with Jekyll. Doing a google search and reading a few blog posts educated me on benefits of Jekyll and static sites in general. I explored Jekyll a little more and loved it immediately.
The first thing that appealed to me about Jekyll was how programmer-friendly it was. Creating a site using Jekyll felt very similar to a developer’s day-to-day tasks. Another thing that appealed to me was Jekyll’s integration with GitHub Pages. Finally, free hosting provided by GitHub Pages (along with the ability to set custom domains) tipped my decision towards using Jekyll.
I have written this post to serve as a stand-alone tutorial, while also trying to keep it short. I briefly describe new terms and concepts as I introduce them, but do not go into much detail. Jekyll’s documentation is excellent and working through Quickstart and Step-by-Step Tutorial should provide you good background on Jekyll.
Let’s get started
Install Ruby Development Environment
You need Ruby development environment setup on your computer. Jekyll documentation provides the requirements list here. In addition, you also need bundler. You can install bundler by using the command gem install bundler.
Jekyll is a ruby gem. Install it by running the following command in a terminal:
Create a new directory for your site
On your computer, create a directory to hold your site:
Create index.html in the new directory
index.html with some content, such as:
Serve the jekyll blog
In a terminal, run the following command
This command generates the site files and runs a local web server at
Install theme gem
You can use a theme to improve your site’s presentation. There is a wide selection of themes to choose from. You can get started with
minima theme which is provided by Jekyll. You can install
minima gem using the following command:
Create a file
Gemfile in the root directory.
Gemfile is used to specify which gems your Jekyll site uses.
Create Jekyll config file and add theme
You also need to set the theme in Jekyll’s configuration file. Jekyll reads configuration from a file named
_config.yml in your site’s root directory. Create
_config.yml with the following contents:
After making any changes to
_config.yml, you need to restart
jekyll serve for Jekyll to pickup configuration changes. Even after restarting
jekyll serve, you will notice no difference in your site’s rendering. You will fix this next.
Update index.html to use a layout
In the previous section, you saw that the text of your
index page rendered without any styling from the theme. This is happening because Jekyll is treating your index.html as a regular html file. You can tell Jekyll to use the theme’s
home layout by adding the following to the top of your
This is called the front matter. Jekyll does additional processing on any file containing a front matter.
Minima theme provides a
home layout which is most suitable for a site’s index page. Among other things
home layout adds a list of recent posts to the home page.
Try in browser. The index page of the site now renders in theme.
Add site title to config
With the site rendered in theme, it looks really good. Like most sites, you want your site to have a title too. The
minima theme uses
title variable’s value (if available) as title of your site. You can set
title variable by adding the line
title: MyAwesomeBlog to
_config.yml should look like this now:
jekyll serve and refresh browser. You will notice that the value for title that you provided in
_config.yml now becomes the title of your site.
Create about page
Create an About page by creating a
about.md file in the site’s root directory.
This page will contain information about me.
This file uses the
page layout provided by the theme.
Try in browser. About link shows up in top bar. Jekyll automatically adds any html or markdown files that are in your root directory to navigation bar, using value of the variable
title from the page’s front matter as link text.
Create projects page
Add another page to your site. Create
projects.md in the site’s root directory.
Projects will be listed here.
Try in browser. The navigation bar now shows Projects link too. Clicking on projects takes you to projects page.
Ordering navigation items
about and project pages added, the site is in good shape now. Suppose you want modify the order of items in the navigation bar with About appearing to the right of
All top-level pages are added to navigation bar in alphabetical order. Reordering navigation items is easily done by using
header_pages configuration setting. Add
header_pages to configuration and set its value to a list of pages in the order you wish them to appear.
Try in browser. The
Project items now appear in your preferred order.
Add a blog post
blog post is as simple as creating a directory and a file within that directory.
Create a folder called
_posts in the root directory of your site. Create a markdown (or html) file with year, month and day prefixed to the filename.
Create a markdown file with year, month and day prefixed to the filename:
This is the contents of this blog
Notice that this file contains Jekyll front matter and sets the layout to post, which is another layout provided by
Try in browser. The site lists the post you just added. Clicking on the post title takes you to the post. Notice that the hyphen separated text portion of the file name becomes the title of the post. Also notice that a link to RSS feed is added.
Adding author name to post
In the blog post, you will notice that there is no author name being displayed. Jekyll minima theme supports
author name setting. It just needs
author variable to have a value. You can set author variable in the front matter of your post. Since it is likely that all posts on your site are written just by you, it is simpler to set
author once in
Add the following to
defaults is special Jekyll setting that allows you to set front matter defaults.
scope specifies which files this rule applies to. A blank path means the rule applies to all files in the site.
jekyll serve and refresh browser page. The post now displays author name.
Deploying to GitHub Pages
This section describes how to host your site on GitHub Pages. GitHub allows you to host one user-level site on github pages. The github pages site for your github account should be created in a repository with the name username.github.io, where username is your GitHub username.
- create a repository on GitHub with the name username.github.io.
- add the github-pages gem to Gemfile. This is a gem provided by GitHub to manage Jekyll and its dependencies. Read this for more details.
- commit and push to your repository.
- after a couple of minutes you can point your browser to http://username.github.io and your should see your site.
Using a custom domain
You can set a custom domain for your site you just deployed as follows:
- purchase a domain name using service of your preference.
- in the root directory of your blog site, create a file
- add the domain name as file’s contents.
- commit and push the changes to your gitub repository.
- to connect the domain name to your site, you need to update
ANAMErecords with your domain register.
- for example, GoDaddy uses
Arecords. If you registered your domain using GoDaddy, you can use IP addresses listed in this article to set
- set the
wwwsubdomain to redirect to
myawesomedomain.comby adding a
CNAMErecord with your domain register. This is not to be confused with the
CNAMEfile that you created earlier.
- if GoDaddy is your domain register, no action needs to be taken. GoDaddy automatically sets the
Add Disqus commenting
Comments are essential component of any site. minima supports Disqus commenting system. Comments can be enabled for your posts by setting a configuration parameter. There are steps to add comments to your site:
- sign-up for Disqus Basic account.
- on Disqus, add your site as organization (you will use
- in your site’s
_config.yml, enable Disqus commenting by adding the following:
commit and push changes to your github repository.
After github pages regenerates the site in a few minutes, navigate to
myawesomedomain.com in your browser. You should see Disqus comments displayed at bottom on your post page. Note that Disqus comments are not displayed when running the site locally using
This post described how you can deploy your personal blog to GitHub Pages hosted site. We used Jekyll site generator since that is the technology that GitHub Pages uses internally. We saw how easy and quick it was to get a basic site up and running. Creating a post was equally straight-forward. Finally, we applied a custom domain to our site.