Utkarsh Gupta

by Utkarsh Gupta on August 7, 2016 under jekyll

5 minute read

In this article, I will be going to quickly walk you through how you can set up your own basic personal blog/website with Jekyll - which you can modify afterwards according to your own needs.

What is Jekyll?

You must be probably wondering why should you use Jekyll over Wordpress or any other CMS platforms. Well, Jekyll is a static site generator created by Tom Preston-Werner. What it does is - instead of using any database, it takes the content, renders Markdown or Textile and Liquid templates and produces a complete, static website ready to be served by Apache HTTP Server, Ngnix or any other web server. It is flexible and supports front-end frameworks such as Bootstrap, etc. According to Jekyll’s README file,

it does what you tell it to do, no more, no less. It doesn’t try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.

Jekyll is the engine behind Github Pages. That means you can serve your website directly from your Github repository without worrying about any hosting!

Unlike Wordpress-that is built with a server side scripting language like PHP, a static website generated by Jekyll is fast, consumes less web resources, more secure (due to absence of any databases) and convenient to host (free by Github Pages).

Install Jekyll

Make sure you have ruby and ruby gems already installed on your local machine. Read the documentation here. Now open up the terminal and type the following command line:

sudo gem install jekyll

Once done, run this command to ensure that jekyll command is functioning.

jekyll -v

You’ll see the Jekyll version as shown:

Create a Jekyll Site

You can either use default Jekyll theme or find one for yourself on the internet. For this tutorial, we are going to stick with the default theme.

Head over to Github and create a new repository by the name {your-github-username}.github.io. My username is UtkarshGpta, hence my repository will be named as UtkarshGpta.github.io. Now go to your repository on Github and copy your HTTPS clone URL as shown:

HTTPS clone address

Now launch the terminal where you want to keep your project on the local machine and run the following commands:

cd your-github-username.github.io
git init
git remote set-url {your-git-https-url}
jekyll new {your-github-username}.github.io

Now you have your blog set up on your local machine. To view it, just run:

jekyll serve --watch

You’ll see some “Server address”. Open that address link on the web browser, and you can now see your blog running on your local machine. Now you’re all set up and can edit this default theme according to your own needs. It should look like this :

Now before adding any new posts, we need to understand the directory structure of Jekyll. I recommend you to go through the Jekyll documentation too.

Understanding Jekyll’s Document Structure

What Jekyll does is, you give text written in your favorite markup language, be it Markdown, Textile, etc. it churns that through a layout or a series of layout files and generates a static website. You have full control over what the content would be, how will it be displayed and all. The basic directory structure of jekyll is:

.
├── _config.yml
├── _drafts
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2005-10-08-hello-world.md
|   └── 2016-04-02-another-post.md
├── _data
|   └── members.yml
├── _site
├── .jekyll-metadata
└── index.html

First comes the _config.yml which is written in YAML. It is the blog’s configuration file where we can specify the blog name, permalink format, host, port number, etc.

_layouts is where we put customized layout for our page or posts. From here we control how and where our content is to be viewed.

_drafts directory stores the drafts of the posts you want to publish. They won’t get published until you move them to _posts directory.

_post is the directory where we sae all of our posts written in Markdown or Textile. These files will be compiled by the Jekyll engine and we get a generated website in _site directory (don’t you touch it).

_data directory contains well formatted site-data.

Start by editing _config.yml file in the root directory. Change the title, description, author name and all. When you’re done, you’re now ready to write a new post.

Writing a New Post

As already mentioned earlier, posts in Jekyll are written in either Markdown or textile. You can use this cheat-sheet to write your post in Markdown.

Naming Convention

Posts in Jekyll need to follow a particular naming convention: year-month-date-{title-slug}.{file-extension}

Just open _posts folder and edit the files keeping the format intact. Don’t touch the Post Front-matter, i.e. the text between two --- lines except for the post title and date. They tell the parsing engine to compile these files. Copy this all and make a new markdown file and name it according to the convention. Now using the cheat-sheet, write your blog in plaintext in Markdown and save. Refresh and you’ll see the changes.

Save your changes as for now. In the next post, I’ll write how to host this blog of yours with Github Pages and access the blog online. Meanwhile, you can customize the files in _layouts folder to change the way content is presented and read around the bits of code.

Set up your Jekyll Blog - Beginners' Guide