How to create a website in 15 minutes using Jekyll?

Tools | 07 May 2017

Jekyll is a static site generator used to design and develop static website that is simple, secure, flexible and powerful.

Static sites offer tons of advantages than dynamic websites. Static site generators such as Jekyll offers way more features than WordPress. Some of the cool advantages are

  • Simple: There is no need of server-side programming. No backend. No server. Basic knowledge on front-end components such as HTML, CSS and JavaScript is enough to build a website.
  • Security: As there is no server or database interaction involved, there is no possibility of attacks. In fact, you can see the entire code of your website rendered through Jekyll.
  • Flexible: As you create your own website, you will have full control over it. Unlike Wordpress which has limited customization options, Jekyll offers full customization. You can add unlimited CSS classes or JavaScript files and even use a CSS preprocessor such as Sass which is highly helpful!
  • Powerful: Your website will behave much faster as there is no server interaction involved.
  • Hosting: After creating your Jekyll website, GitHub pages offer free hosting of Jekyll sites using GitHub. You just need a GitHub account and a repository to make your site live!

In this tutorial, we will create our first awesome website using Jekyll, host it in GitHub for free and get our free domain name similar to https://gogul09.github.io in 15 minutes.

Install Ruby in Windows

First, you need to install Ruby which is available here for Windows. Simply download the installer and complete the setup. After that, open up a command prompt and type gem -v. You should get something like this.

cmd gem -v
1
2.5.2

Also, you can type ruby -v and should get something like this to proceed.

cmd ruby -v
1
ruby 2.3.3p222 (2016-11-21 revision 56859) [i386-mingw32]

Now, install bundler which provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

cmd
1
gem install bundler

Install Github pages gem

After installing ruby, you need to install a gem called github-pages that includes all the dependencies and jekyll too.

cmd
1
gem install github-pages

Verify you have installed Jekyll by typing jekyll -v in the command prompt.

cmd jekyll -v
1
jekyll 3.4.3

That’s it! You have installed all the dependencies to create your first awesome website.

Creating a new jekyll site

Before creating your first website, you need to follow a folder structure to keep everything organized. In case if you wish to create multiple sites, proper folder structure reduces so much stress in future while maintaining it. I follow the one below inside which all my websites are kept inside its own folder.

path folder structure
1
2
3
4
5
6
g:\workspace\web

g:\workspace\web (root-folder)
  -- first_awesome_website (sub-folder)
  -- second_cool_website (sub-folder)
  -- third_amazing_website (sub-folder)

To create your first website, open up a command prompt, get into the above folder structure and type in the first Jekyll command jekyll new site_name. For this tutorial, I will keep the name of the website as first_awesome_website. You can keep any name as you like.

cmd jekyll new first_awesome_website
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
Running bundle install in g:/workspace/web/first_awesome_website...
Bundler: Fetching gem metadata from https://rubygems.org/...........
Bundler: Fetching version metadata from https://rubygems.org/..
Bundler: Fetching dependency metadata from https://rubygems.org/.
Bundler: Resolving dependencies...
Bundler: Installing public_suffix 3.0.2
Bundler: Using colorator 1.1.0
Bundler: Installing ffi 1.9.25 (x86-mingw32)
Bundler: Using forwardable-extended 2.6.0
Bundler: Installing rb-fsevent 0.10.3
Bundler: Installing ruby_dep 1.5.0
Bundler: Installing kramdown 1.17.0
Bundler: Using liquid 3.0.6
Bundler: Using mercenary 0.3.6
Bundler: Using rouge 1.11.1
Bundler: Using safe_yaml 1.0.4
Bundler: Installing thread_safe 0.3.6
Bundler: Using bundler 1.14.0
Bundler: Installing addressable 2.5.2
Bundler: Installing rb-inotify 0.9.10
Bundler: Installing pathutil 0.16.1
Bundler: Installing tzinfo 1.2.5
Bundler: Installing sass-listen 4.0.0
Bundler: Installing listen 3.1.5
Bundler: Installing tzinfo-data 1.2018.5
Bundler: Installing sass 3.5.6
Bundler: Installing jekyll-watch 1.5.1
Bundler: Installing jekyll-sass-converter 1.5.2
Bundler: Using jekyll 3.4.3
Bundler: Installing jekyll-feed 0.10.0
Bundler: Using minima 2.1.1
Bundler: Bundle complete! 4 Gemfile dependencies, 26 gems now installed.
Bundler: Use `bundle show [gemname]` to see where a bundled gem is installed.
New jekyll site installed in g:/workspace/web/first_awesome_website.

After executing the above command, Jekyll creates your website with default settings. You can go into the below path to check the contents that Jekyll has created.

pathg:\workspace\web\first_awesome_website
1
2
3
4
5
6
_posts
_config.yml
about.md
Gemfile
Gemfile.lock
index.md

We will look into all the above contents in a while. But before that, let’s see your website locally.

Get into the folder that we created first_awesome_website and execute the following two commands.

cmdgenerate & run locally
1
2
jekyll build
jekyll serve

Above two commands should return results similar to the one shown below.

outputjekyll build
1
2
3
4
5
6
7
8
9
10
11
12
WARN: Unresolved specs during Gem::Specification.reset:
      rb-fsevent (>= 0.9.4, ~> 0.9)
      rb-inotify (>= 0.9.7, ~> 0.9)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
Configuration file: g:/workspace/web/first_awesome_website/_config.yml
            Source: g:/workspace/web/first_awesome_website
       Destination: g:/workspace/web/first_awesome_website/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.588 seconds.
 Auto-regeneration: disabled. Use --watch to enable.
outputjekyll serve
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
WARN: Unresolved specs during Gem::Specification.reset:
      rb-fsevent (>= 0.9.4, ~> 0.9)
      rb-inotify (>= 0.9.7, ~> 0.9)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
Configuration file: g:/workspace/web/first_awesome_website/_config.yml
Configuration file: g:/workspace/web/first_awesome_website/_config.yml
            Source: g:/workspace/web/first_awesome_website
       Destination: g:/workspace/web/first_awesome_website/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.378 seconds.
  Please add the following to your Gemfile to avoid polling for changes:
    gem 'wdm', '>= 0.1.0' if Gem.win_platform?
 Auto-regeneration: enabled for 'g:/workspace/web/first_awesome_website'
Configuration file: g:/workspace/web/first_awesome_website/_config.yml
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

Now, you can visit our website locally at http://localhost:4000/. You should get something similar to the one shown below.

Figure 1. Our first awesome Jekyll website.

Awesome! You have made your own website using Jekyll in minutes. To quit the running procees, you can press CTRL + C in the command prompt. To view the site again locally, just type the command jekyll serve and view it in the browser at the same address http://localhost:4000/.

Keep in mind that you haven’t yet hosted your website. Hosting the website means you need a dedicated space in the internet for people to view your website if given a URL. GitHub Pages provides free web hosting for sites made from Jekyll. We will discuss it soon.

Running a jekyll site locally provides the following advantages.

  • You can tweak/edit the site multiple times before making changes to the live website.
  • You can use your favorite text editor to write your posts in Markdown and view the changes instantly in the browser locally.
  • Only after making all the necessary changes, you can push it to GitHub and see it live.

Basic files & folders

Now, we will look into all the default files and folders created by Jekyll inside your master folder.

  • _posts: This is the folder inside which all your blog posts will be kept. Whatever you write in this folder will be converted to html and corresponding styles will be applied automatically. All files must strictly follow the naming convention for proper parsing and display.
ruledefault naming convention for a blog post
1
yyyy-mm-dd-<post_name>.md
  • _site: This is the folder generated by Jekyll which will be used for distributing your website. All content inside this folder is what makes your site live. This folder gets updated automatically as you make changes. Do not update or delete or add anything inside this folder.
  • config.yml: This is the YAML configuration file or shortly, the settings file for your site. It looks like the one shown below.
fileconfig.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.

# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via , , and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via .
title: Your awesome title
email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: jekyllrb
github_username:  jekyll

# Build settings
markdown: kramdown
theme: minima
gems:
  - jekyll-feed
exclude:
  - Gemfile
  - Gemfile.lock

This is basically a key-value file which is used to store important configurations for your website. Any changes made to this file requires terminating your local server process and restarting it. You can now modify the keys present in this file with your own values.

Hosting in GitHub Pages

Before jumping into the concepts of Jekyll, let’s first host your website in GitHub pages for free so that you will get your unique URL with which you can see your website live in the internet.

To host a Jekyll site in GitHub, you need a GitHub account. Make sure you follow that link to create a github account.

Now, you need to create a repository that acts as a container or master folder for your website. The name of your repository must be unique and this name is what you will be using to generate your unique GitHub URL. GitHub offers a free domain name for your website which comes like

linkGitHub pages link format
1
https://yourusername.github.io

Follow this link to create a repository with the exact name as your GitHub account name with .github.io appended.

For example, my github account name is Gogul09 and so, I created a repository with the name Gogul09.github.io.

Execute the following git commands one by one to take your website to the GitHub repository that you created. Make sure you are still in the master folder first_awesome_website that you created in the command prompt at the beginning of this post and then execute these commands.

cmdgit commands
1
2
3
4
5
git init
git add . 
git commit -m "first commit"
git remote add origin https://github.com/yourusername/yourrepo.git
git push origin master -f

After 5-10 minutes, you will be seeing your website using the below link.

link
1
https://yourusername.github.io

Congratulations! You have created your first website using Jekyll and hosted it for free using GitHub pages.

Powerful Sass Integration

If you don’t know the capabilities of a CSS preprocessor such as Sass, I highly encourage you to learn it. Using sass, you can make your CSS more structured, elegant and easier to modify.

When you develop websites, there comes a time when your single CSS file goes out of hands and its difficult to update a CSS class or modify a layout. In such situations, Sass is highly useful.

Jekyll has powerful integration for Sass. In fact, Jekyll comes with its own Sass compiler. Here are the steps to make use of Sass for your website.

  • Create a folder named _sass in the root directory which is first_awesome_website for this tutorial.
  • Create a file named style.scss in the root directory.
  • Append the below lines in your _config.yml file.
code_config.yml
1
2
sass:
  style: compressed
  • First two lines of your style.scss should include triple dashes like the one shown below. After that you can use this file as the master Sass file for your website. You can also import Sass files residing inside _sass folder as shown below.
code_config.yml
1
2
3
4
5
6
7
8
9
10
---
---

@import "typography";
@import "colors";

// start writing after this
div {
  width: 100%;
}

Note: Any file inside _sass folder must have _ appended to its name. For example, this is a Sass partial file - _typography.scss.

Customizing layout and style

The default theme provided by Jekyll is awesome and responsive. If you wish to override the default theme, carry on. For the rest of this tutorial, follow the below steps to modify the layout of your website and include custom styling.

  • Create two folders in the root directory. _includes and _layouts.
    • _includes folder will include all the pieces that comes repeatedly in your website such as header, footer, meta etc. We will create three files inside this folder for now.
      1. meta.html will hold all the meta tags inside head tag.
      2. header.html will hold all the header related elements such as logo, navigation bar etc.,
      3. footer.html will hold all the footer related elements such as copyrights etc.,
codemeta.html
1
2
3
4
5
6
7
8
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">

<title> "{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %} </title>

<link rel="stylesheet" type="text/css" href="/style.css" />
<link href='https://fonts.googleapis.com/css?family=Nunito' rel='stylesheet' type='text/css'>
codeheader.html
1
2
3
<header>
  <h2>{{ site.name }}</h2>
</header>
codefooter.html
1
2
3
<footer>
  <p>Made with the awesome Jekyll</p>
</footer>

Now, create a file named default.html inside _layouts directory. This will act as the blueprint for your website.

codedefault.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!DOCTYPE html>
<html>
  <head>
     {% include meta.html %} 
  </head>

  <body>
     {% include header.html %} 
    
    <div class="container">
      <div></div>
      <article>
         {{ content }} 
      </article>
      <div></div>
    </div>

     {% include footer.html %} 
  </body>

</html>

Cool! Open up index.md and replace it with the following content.

1
2
3
4
5
6
7
8
9
10
11
12
13
---
layout: default
---

<h3>Welcome to my Blog</h3>

<div>
  {% for post in site.posts %}
    <ul>
      <li><a href="{{ site.baseurl }}{{ post.url }}">{{ post.title }}</a></li>
    </ul>
  {% endfor %}
</div>

Awesome! Open up style.scss and replace it with the following content.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
---
---

body {
  background-color: #ffffff !important;
  margin: 0px;
  padding: 0px;
  font-family: "Nunito", sans-serif;
}

header {
  padding: 20px;
  background-color: rebeccapurple;
  text-align: center;

  h2 {
    color: white;
    font-weight: 100;
  }
}

footer {
  position: fixed;
  bottom: 0;
  right: 0;
  height: 60px;
  background-color: black;
  text-align: center;
  width: 100%;
  
  p {
    color: white;
    height: 60px;
    margin-top: 20px;
      font-size: 13px;
  }
}

.container {
  display: flex;
  margin-bottom: 100px;
  div {
    flex: 1;
  }
  article {
    flex: 1;
  }
}

article {
  background-color: #eaeaea;
  height: 100%;
  padding: 20px;
  h3 {
    text-align: center;
  }
}

.post-header {
  background-color: #252525 !important;
    border-radius: 10px;
    box-shadow: inset 0 3px 30px black;
  h1, p {
    color: white;
    font-weight: 100;
  }
}

Now, if you see your website locally http://localhost:4000, it will look like the one shown below.

Figure 2. Front page.
Figure 3. Post page.

Start exploring what we did above and your imagination is all that is needed to beautify layouts and styles.

References

In case if you found something useful to add to this article or you found a bug in the code or would like to improve some points mentioned, feel free to write it down in the comments. Hope you found something useful here.

Happy learning!