Getting started with Jekyll - installation, project setup & deployment

by Jay Mistry · Jun 24, 2019

Build your blog with Jekyll

Hello everyone! This is the very beginning of the Build your blog with Jekyll tutorial series.
Let’s answer some questions that you may have, before we start developing our blog!

Why use Jekyll when…

This site is also created using Jekyll, you can check out the Lighthouse score of this site-

Tech no Kami lighthouse score

If you have any other questions in mind, you can ask me and I’ll update the post accordingly. Now, with the common questions out of our way, we can start building our blog.

Install Jekyll and Bundler

We need Jekyll and Bundler gems to build our Jekyll site. Though Bundler is not a requirement, it is recommended as it will make sure that the version of Jekyll used for building your site is always the same. Jekyll gem is required to build our Jekyll site.

First make sure that you have Ruby installed on your system by executing the following command-

  $ ruby -v
  # ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]

If you get an output similar to the one commented above, Ruby is installed. Else, you can visit official Download Ruby site and install it according to your operating system.

Now, install Jekyll and Bundler gems using the following commands-

  $ gem install bundler jekyll

You can check if it is installed by executing the following commands-

  $ jekyll --version # jekyll 3.8.5
  $ bundler --version # Bundler version 2.0.1

Now, we are good to go! If you are still facing problems in installation, you can visit Official Docs and view detailed installation steps as per your operating system.

Setting up our project

Throughout this series, we will create a site which displays the data of our favourite anime characters! Let’s name the site ‘OtakuBook’ ( it’s quite original 😉️).

  $ mkdir OtakuBook
  $ cd OtakuBook/

Jekyll requires a _config.yml file and a _layouts folder to build a site. The configuration file _config.yml can be empty. We will keep our site layouts in the _layouts folder. We will also create a base.html layout which will serve as a parent layout for all the pages.

  $ mkdir _layouts
  $ touch _layouts/base.html
  $ touch _config.yml

For creating Jekyll pages, we can use HTML and Markdown. For text-rich content, Markdown is the way to go, but for pages with complex elements, HTML files can be a choice too. We will use HTML file for our home page and Markdown for our ‘About’ page. Let’s create them.

  $ touch index.html about.md

Let’s start creating our basic layout of the site. We will have a navigation bar at the top, content in the middle and a footer. To speed up development for the sake of this tutorial, I will use Bootstrap 4 but I will also show you how you can style your pages using SCSS.

_layouts/base.html
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
    
    <title>OtakuBook</title>
  </head>
  <body>
    <!-- Navbar -->
    <nav class="navbar navbar-expand-lg navbar-dark bg-primary">
      <div class="container">
        <a class="navbar-brand" href="#">OtakuBook</a>
        <ul class="navbar-nav mr-auto">
          <li class="nav-item">
            <a class="nav-link" href="/">Home</a>
          </li>
          <li class="nav-item">
            <a class="nav-link" href="/about/">About</a>
          </li>
        </ul>
     </div>
    </nav>

    <!-- Our main content -->
    <div class="container">{{ content }}</div>
  </body>
</html>

The classes used for the navbar are Bootstrap classes, and can be referred to on Bootstrap’s documentation. In the navbar, we have two links, one to the home page and one to the about page. In the div tag of our main content, we see liquid syntax that prints the content of the page which would use this file as it’s layout in the div.

Let’s create two pages for our website - a home page and an about page.

index.html

---
title: "Home"
permalink: "/"
layout: base
---


<h1>Home</h1>
<h3>Welcome to the greatest Anime Characters Databook</h3>

<p>Dummy content...</p>

<p>Dummy content...</p>

The statements enclosed between the ‘---’ is called the front matter of the page. It holds important information regarding the page like title, permalink, layout, tags, categories, etc.
Permalink is the route at which the page should be displayed. For ‘index.html’, the permalink is ‘/’, so it will be displayed at ‘http://mydomain.com/’ i.e. the home route.
We want to use ‘base.html’ file as our layout, so we use the name of file - ‘base’ in the layout field.

about.md

---
title: "About"
layout: base
permalink: "/about/"
---


# About OtakuBook

We love watching anime, so we bring to you the **World's Greatest** Anime characters Databook!

This file is in the Markdown format. As you can clearly see, for text-rich pages, Markdown offers a very clean syntax. You can learn more about Markdown here. I would recommend you to invest your time in learning Markdown syntax.

That’s it!

Believe it or not, our Jekyll site is ready to be served! We can serve our site locally using the following command-

  $ bundle exec jekyll serve

The site will be hosted on http://localhost:4000 on your system. Let’s take a look at what we built!

How to create a Jekyll blog demo

Deployment

You can learn how to setup your site on GitHub Pages here. The process is the same, and the explaination is in detail, so you wouldn’t face any problems in deploying your site.

We will take a look at the real power of Jekyll in the next tutorial - posts. Till then, you can learn more about Jekyll from their official docs.

That’s it for this tutorial, we will meet in the next one!

Adios folks!