A Step-by-Step Guide to Building Your Own Website Using Jekyll — I

I had often thought of building my own website. But since I had little knowledge of web-development and almost zero imagination in front end, I could never put that thought to execution.

However, Jekyll came to my rescue. Don’t worry if you don’t know the concepts of web-development. This guide will help you set up your own website and give you full control over it too, i.e.

You can change the themes as per your need. If you don’t like a feature, you can remove it or modify it.

The official documentation of Jekyll is available here. But personally, I could not gather much from it, and had a tough time figuring out stuff.

Outline

We’ll setup a website on github. Since ‘github-pages’ come with inbuilt support for Jekyll, hosting your webpage on github becomes very easy.

Requirements

• A github account (don’t have one, sign up here)
• Linux / Mac OS
• Familiarity with git concepts like push, pull, clone and commit

Installation

Let’s decide the theme first. Here is a list of Jekyll themes which are supported by github pages. Decide which theme you want to use. For this guide, I’ll be working with the Cayman theme.

The Cayman Theme. Every theme will have a `View on Github` option.

Go to the theme which you like. Click on View on Github.

That should open a page like this. Either click on fork or Clone or download.

For this guide, I’ll be cloning the directory into my local. When you click on Clone, you’ll get something like this:

Copy the link (in this case https://github.com/pages-themes/cayman.git)

Open the terminal (on either Mac or Ubuntu), cd to the folder you want to save the code in, and run the following:

$ git clone whatever_you_copied

So supposing you wanted the code in your Documents folder, and you were using the Cayman theme, run:

$ cd Documents
$ git clone https://github.com/pages-themes/cayman.git

The above clones the repository to your local. Now you’ll find a folder with the theme name (for those using Cayman, the folder name would be Cayman).

Next do the following in your terminal:

$ cd Cayman ##replace this with your theme name
$ script/bootstrap

Viewing what you installed

Next run the following command:

$ bundle exec jekyll serve

If everything goes well, you should see the following on your terminal:

Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Open any browser of your choice, and go to either of the following links:

http://localhost:4000
http://127.0.0.1:4000

You should see a webpage corresponding to your theme.

Changing what you view

Now we come to the part where we take control over our website.

Step 1 (Changing the title) :

Navigate to the theme folder (in our case, Documents/Cayman), and open the file _config.yml on a text-editor of your choice. The contents would look like this:

title: Cayman theme
description: Cayman is a clean, responsive theme for GitHub Pages.
show_downloads: true
google_analytics:
theme: jekyll-theme-cayman

Supply an appropriate title and description. For example:

title: Shadow
description: Apparently this user prefers to keep an air of mystery
show_downloads: true
google_analytics:
theme: jekyll-theme-cayman

And the webpage changes accordingly:

Note that you may need to perform a hard refresh for the changes to reappear, as the browser may use cache to render the webpage. So press CTRL+SHIFT+R (or on Mac, do a CMD+SHIFT+R).

Step 2 (Changing the Content) :

Navigate to the theme folder (in our case, Documents/Cayman), and open index.md on a text-editor of your choice.

Notice how the contents on index.md are rendered on your webpage. This is the beauty of Jekyll. It automatically generates html file from the md file, and thus our work is reduced to a mere writing of plaintext.

Play around with index.md, and notice how the webpage changes. Once you’re done with that, your basic webpage has been set up.

Step 3 (Start Blogging):

The primary use case of Jekyll is to generate static sites without worrying about HTML and CSS specifications. So, it finds great use for bloggers, where once the initial set up is done, you can start blogging — focusing only on the content of the blog and not having to worry about the layout.

Blogs go under the _posts folder. Navigate to the Documents/theme folder, and create a _posts folder.

You can create blogs in the _posts folder, but note that the names of blog files follow a prescribed format. The name of blogs should be in the format:

YYYY-MM-DD-Title_of_blog.md

Create a file named 2020-06-03-first-blog.md. Put the following inside the file:

---
layout: default
description: This is my first blog
---
# This should be the top heading
## This should be a subheading

The first blog is ready. You can see it on:

http://localhost:4000/2020/06/03/first-blog.html.

It will appear as follows:

Notice how the title (First Blog) is picked up from the file name itself, and the description (This is my first blog) is picked up from description: This is my first blog .

Now you can create your blogs as well. So most of the work is done. The only thing which remains is to add links to these blogs on your home page, so that others can reach your blogs from the home page itself.

Listing Your Blogs

Wouldn’t it be great if you had a page, on which all the blogs were automatically listed. Turns out, we can have this functionality using Jekyll.

Let us design a page for listing our blogs. Create a folder named blog on the Documents/Cayman (or wherever your theme is). Create a file called index.md in it. Put the following into index.md :

---
layout: default
---
# Blogs
{% for post in site.posts %}
 
<ul>
 
<li><h3><a href="{{ post.url | relative_url }}">{{ post.title }}</a></h3></li>
 
</ul>
{% endfor %}

Now go to the site: localhost:4000/blog , and you’ll be able to see your blogs listed there. You might see something like this:

This is the power of Jekyll. You needn’t worry about listing your blogs on the page. All you have to do is create blogs, and Jekyll would take care of the rest.

Explanation of what the code means

The first part tells which layout to use to render the page. layout:default means use the default layout to render the page. If you want to see how the default layout is configured, look at the default.html file in _layout folder.

You can change the default.html file, or add another html file in _layout and use that to render some page. More on this to follow later.

Another thing to note is the index.md file in blog folder. Try and understand how HTML syntax works with the markdown syntax. Notice that # is not an HTML tag, but is converted to a header tag internally by Jekyll.

However, <ul> , <li> , <a> are all HTML tags and can be used as are in the md file.

The following is Jekyll syntax:
{% for post in site.posts %}.

This is basically a for-loop over all the posts in the site. Note that {{ post.title }} and {{ post.url }} are internally compiled by Jekyll to their respective values.

Adding a link to blog homepage

Go to your index.md file in theme folder (in our case, Documents/cayman). Add the following line after the layout specification (or something similar — start controlling your website now):

You can find my blogs [here](./blog/)

Now go to localhost:4000, and you should see something like this:

Notice the top line below the title and description. Note how the word `here` is highlighted

If you click on here, you’ll be redirected to the blogs page, where all your blogs are listed.

Going Live

With the repo in place, you can now push all this code to your github account (create an appropriate repository, like shadow.github.io).

Please go through this link to configure the github-pages publishing source for your repository.

If everything goes well, your site should be live at: https://repo_name.github.io, or in my case, https://shadow.github.io.

Taking Full Control

The part 2 of this blog assumes a working knowledge of HTML, CSS and JavaScript. You may ignore this if you are not familiar with the above, or if you are content with the website you have.