Sometimes you want to create a simple blog or website and deploy it easily, with no cost. It may seem hard but it's actually easy with Jekyll!

If you're not familiar with Jekyll, it helps you create a simple and static websites. You can just write your content in HTML or Markdown.

In this post I will teach you how to create a blog with Jekyll in easy steps, and then deploy it on GitHub pages for free!

Installing Jekyll

To start with Jekyll, you first need to install some prerequisites on your system. You can find here on Jekyll's website detailed guides on how you can do it based on your system.

Once you install the prerequisites, you can use the following command to install Jekyll:

gem install jekyll bundler

Create Website

Now you can create your website! It takes just one command:

jekyll new tech-blog

We're calling our website tech-blog, you can replace that with whatever name you want for your website. This command will create a new folder with all the files necessary for your Jekyll website.

Adding Jekyll to An Existing Project

The command above will create a new project from scratch. If you already have a project that you want to add Jekyll to, you can add the --force option like this:

jekyll new tech-blog --force

This will add Jekyll to your existing directory tech-blog that has your project.

Build and Start Website Locally

After creating the Jekyll website above, change the directory to be inside the website directory

cd tech-blog

Then, build and serve the website locally with the following command:

bundle exec jekyll serve

Then go in your browser to localhost:4000 and you will see your new blog up and running!

By adding the option --livereload to the above command, your website will live reload as you make changes to files

bundle exec jekyll serve --livereload

Adding Pages

Let's try adding a new page to our website. In the root of the website's directory, create the file helloworld.md with the following content:

---
layout: page
title: Hello World
permalink: /hello-world/
---

Hey There!

The lines between the three dashes are like the header of the page that define meta information about it. Here we have three information:

  1. layout: It means what will be the layout of the page. By default, it can be default, home, page or post. You can also add your own custom layouts.
  2. title: The title of the page.
  3. permalink: the url of the page.

Once you add the file and save the content in it, you can refresh the page of your website and see a new link is added to the Navigation bar, or if you had --livereload in your command then it will have already refreshed the page for you. Click on it and see the new page we just created.

You can try editing the content of the file under the three dashes and see the changes.

Here, we created this page using markdown. You can also do the same thing with html files

---
layout: page
title: Hello World
permalink: /hello-world/
---

<div>Hey There!</div>

Adding Posts

If the website you are creating is a blog, you can add posts in the _posts directory. Files for posts need to start with the date of the post in the format YYYY-MM-DD then followed by the name of the post in slug format.

Create a new file _posts/2020-12-15-my-first-post.md (or HTML, both can work) with the following content:

---
layout: post
title:  "My First Post"
categories: updates
---

This is my first post. Thank you for reading it!

Once we save it and go to our website, we will see a new post added on the home screen.

Changing Website Information

To change your website/blog's information like title or URL, all meta information is included in the _config.yml file.

The _config.yml file by default has the following keys:

  1. title: The title of the website.
  2. email: Contact email that will also appear in the footer.
  3. description: Description of the website. Will also appear in the footer.
  4. baseurl: The subpath of the website, for example /blog
  5. url: The URL of the website
  6. twitter_username: Your twitter username, which will appear in the footer.
  7. github_username: Your GitHub username, which will appear in the footer.
  8. theme: the theme of your website. By default it's minima.
  9. plugins: The plugins you will use on your website. By default there's only jekyll-feed.

For a full list of configurations, check them on Jekyll's website. Also, Minima have additional configuration as well.

Let's try changing the website title:

title: Tech Blog

Changes to _config.yml will not be shown by refreshing or through live reload. You need to restart the server.

If you restart the server and go to the website now, you will see that the website name has changed in the navigation bar, footer, and anywhere else it might be used.

Making Changes to Home Page

All changes in the Home page should be made in index.markdown. By default, it uses the home layout which shows the list of posts you have. However, you can change the layout of the page or add any additional content to it.

Let's try adding some content to it:

---
# Feel free to add content and custom Front Matter to this file.
# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults

layout: home
---

This is my tech blog

Everything between the dashes is already there by default. We just added the line "This is my tech blog". If you go to your website now, you will find that this line has been added above the posts.

Using Assets

Any assets that you add in the root of the directory will automatically be included in the Jekyll build. These include CSS and Javascript files or images.

To add CSS to your website, you have two options:

  1. Copy the content of main.css in the _site directory, then create a new file in the root of your directory assets/main.css with the content you copied. Then you can make any additions to it and it will be shown.
  2. Create a new file and add it to the head of the website.

To do it with the second method, first create the file assets/styles.css with the following content:

.site-title, .site-title:visited {
    color: #f00;
}

We're just changing the color of the title here. Then, we need to include it in the <head> of the website. To do that, you need to copy the content of includes/head.html from minima (or whatever theme you are using), then create _includes/head.html in your root directory with the following content:

<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {%- seo -%}
  <link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}">
  {%- feed_meta -%}
  {%- if jekyll.environment == 'production' and site.google_analytics -%}
    {%- include google-analytics.html -%}
  {%- endif -%}
  
  
  <link rel="stylesheet" href="{{ "/assets/styles.css" | relative_url }}">
</head>

Everything before the last line is from the minima theme. The last line is what we added, which is a link to the stylesheet we created assets/styles.css.

If you go to the website now, you'll find that the color of the title of the page has changed.

Optional: Using Sass

You can also use Sass instead of CSS. To do this, first you need to add the following to _config.yml:

sass:
    sass_dir: assets
    style: compressed

sass_dir is necessary if you are using imports inside sass files.

Then, create the file assets/styles.sass with the following content:

---
---

.site-title, .site-title:visited
    color: #f00

The first two dash lines tells Jekyll to compile and add this file to the build. After that, you can add any styles you need.

Finally, we need to import it in the <head> of the page. The previous head code can be used, as assets/styles.sass will be compiled to assets/styles.css.

If you now refresh the page, you'll see that the site title color is red.

Deploying to GitHub Pages

Once you are done making the website, you can now deploy it on GitHub pages for free.

First, you need to have a repository for your website on GitHub. If not, then create one and commit your work to it.

Next, go to Settings and scroll down to GitHub Pages

Here, you will need to pick a Source branch and then the root directory. Click Save, and GitHub will start compiling your website.

However, it will not work right away. There are some changes you need to make in the website.

In _config.yml you need to change three key values:

  1. baseurl: this needs to be the subpath of the website
  2. url: this is the main URL of the website.
  3. destination: The directory in which the build goes to

When creating a website in GitHub pages, usually the format of the URL will be: https://USERNAME.github.io/REPOSITORY-NAME

So, baseurl should be /REPOSITORY-NAME part of your URL, and url should be https://USERNAME.github.io part of your URL.

Since we are deploying this to GitHub pages, by default it uses the content of docs directory in your repository. So, add a destination key in _config.yml and set it to ./docs

destination: ./docs

Then create a docs directory. But we don't want the content of docs to be available in the repository. So, create an empty .gitkeep file in it. This is necessary to make sure that the docs directory can be committed to the repository. Then, add the following to .gitignore:

docs/*
!docs/.gitkeep

This will make sure that the content of the docs directory will not be added except for .gitkeep.

Once you commit and push all these changes to your repository, your GitHub Pages will be built again and once it's done you can view it on your designated URL!

Conclusion

So many additional settings and configurations can go into creating your Jekyll website. This tutorial aims to keep it as simple as possible. You can check out Jekyll's website for documentation on how to create or choose different Themes, Plugins, and more!