Jekyll: Ultimate Guide for Creating Websites with Jekyll

In this article, we are going to explain how Jekyll works and how to create a blog with Jekyll (and publish it for free to GitHub Pages).

Jekyll is a static website generator, which was introduced in 2008 by Github Co-founder Tom Preston-Werner. In the early days, web content was written in plain HTML and published online. Later, platforms like Blogger and WordPress made it possible to write content a web editor and generate a website from it. Squarespace and Wix allowed the creation of websites simply by dragging and dropping. But, these platforms had two main problems: complexity and slowness. In this article, I'm going to explain how Jekyll works and how to create a blog with Jekyll (and publish it for free to GitHub Pages).

  1. How Jekyll Works

  2. How to create a blog with Jekyll

Jekyll Island, United States (Not Related)
Jekyll Island, United States (Unsplash) - Not Related To Jekyll Blogs

1. How Jekyll Works

Jekyll, the official website at, is a static site generator that is built to be minimal, fast, and easy to manage. This quote from the official website explains what Jekyll does.

Jekyll 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

Jekyll is the engine behind GitHub Pages. Hence, we can host Jekyll Blogs on Github Pages for free. To our surprise, GitHub Pages supports custom domains. Therefore, we can host it there while having our own domain name (

Facts about Jekyll

  • Uses Markdown

  • Uses Liquid Templates

  • 0.01% of websites use Jekyll (Source)

  • Jekyll is installed as a Ruby Gem on local computers.

  • Jekyll does not parse files on each request. It creates static pages and saves them in the _site folder on the build. Files are statically served through a server.

  • Jekyll does not use databases.

Demystification: A common confusion among those who are new to Jekyll is considering Jekyll as a blogging software (or Content Management System) - it is not! Jekyll is only an engine to parse files. In WordPress, you can write on a web-based rich editor and publish content. However, in Jekyll, you write content in Markdown in a plain text editor. Then, you publish new updates online. (Make sure you are fine with that.)

Who is it for?

Jekyll is not for everyone. If you want to easily drag and drop and build your website, go for something like Squarespace or Wix. If you want to easily add plugins to extend features, easily customize themes through a dashboard, or want to write content in a dashboard, go for WordPress (which is used by 40% of the internet). Choose Jekyll if you like to work with plain text files, write content in Markdown, and use the command line/terminal. In fact, Jekyll is a great choice if you are someone who codes. And, Jekyll is a lot faster than other alternatives because of how it works.

2. How to create a blog with Jekyll


While coding knowledge isn't necessary to set up or use Jekyll, an understanding of the following concepts is needed.

  • Markdown - This is how content is written in Jekyll. It doesn't take much time to learn markdown. Check out the Markdown cheatsheet.

  • Git - Used to version control the code. As we will be using GitHub to host our code, you need to be familiar with Git version control. If you aren't familiar with it, I suggest you start with the Git Handbook by Github.

  • Command Line - A little experience using the command line will be essential. If you don't have that experience, don't worry. You'll only need to know how to open the command line and navigate to a folder (Search Google with your OS).

(Note for non-devs: The process seems overwhelming. But, it's easy. You just need to get accustomed to it.)

I'd like to break down the process into 3 steps.

  1. Setting up Jekyll locally

  2. Setting up Github and Github Pages and deploying

  3. Customizing

1. Setting up Jekyll Locally

Jekyll is written in Ruby. So, you have to install it first on your computer.

Next, you need to install two Ruby Gems (Ruby Gems are packages that add functionalities to Ruby projects)

Here, we will install jekyll and bundler Gems using the gem command which will be available after installing Ruby. Open the command line and run the following code.

1gem install jekyll bundler

Then, navigate to the folder where you need the new blog to reside. (Ex: In windows, cd F:\MyProjects)

Next, run the following command to install a new Jekyll site.

1jekyll new my-blog

This installs the Jekyll files in the my-blog folder in the current directory. Next, navigate to that folder.

1cd my-blog

Final command:

1bundler exec jekyll serve

This will serve the newly created static site at http://localhost:4000. Visit the URL on your web browser and see your beautiful Jekyll site.

There, you'll notice some placeholder values such as We'll change them and write our first post now.

Changing Configuration

Open _config.yml and do some editing. It is a YAML file. Thankfully, Jekyll's config file explains the YAML syntax in itself. So, see the instructions in the file before editing it.

1title: My Cute Jekyll Blog
3description: >-
4 This is my cute jekyll blog. I post some awesome stuff every day.
5baseurl: ""
6url: ""
7twitter_username: MyCuteJekyllBlog
8github_username: MyCuteJekyllBlog

The serve command automatically updates the static content when you edit the content and data files. However, after editing _config.yml, you have to restart the server!

Creating the First Blog Post

All posts are saved in the _posts folder.

All posts should have the format. Some examples are:



All posts start with a Front Matter, a YAML code between triple-dashed lines.

2layout: post
3title: Best Tools for Remote Teams
4bestTool: SomeTool

In Front Matter, you can set values for predefined variables or define new variables. In the above example, layout and title are predefined variables while bestTool is a new variable that can be accessed on the page as follows.

All blog posts have the layout type post.

2layout: post
3title: Best Tools for Remote Teams
4bestTool: SomeTool
6<h2>The Best Tool is {{ page.bestTool }}</h2>

Now, you know how to create a blog post. Create one and save it in the _posts folder. Then, reload the site. You'll see new updates in real time.

2. Setting up Github and Github Pages and deploying

Up to now, we created our Jekyll blog locally, customized the configuration, and published our first post.

Now, we are going to deploy it.

First of all, we have to version control our site using Git. Run the following commands in the folder of the site.

1git init
2git add .
3git commit -m "Initial Commit"

When installing Jekyll, it should automatically create a .gitignore file in the root with at least the following content. (If not, create one).


Then, log in to GitHub and create a new repository named

Next, copy the HTTPS URL of the repository.

Copying the Github Repository URL before deploying Jekyll Site

Then, add the remote repository and push the code. (Make sure to replace the link with your own one).

1git remote add origin
2git push origin master

Done! Your site must now be available on ?

Updating a post

After updating a post (or posts) all you have to do is commit and push the changes.

1git add .
2git commit -m "Updated x post"
3git push origin master

3. Customizing

You can do several things to customize and add functionalities to your static site.

1. Add Comments

Static sites do not have databases. So, you have to use a third-party commenting system on your site. You can use Hyvor Talk, a privacy-first ad-free, and fully-customizable commenting platform. It only takes a few minutes to set up (just copying and pasting code).

See How to add Hyvor Talk comments to Jekyll?

Recommended Reading: Why Hyvor Talk is a better option for static sites than its alternatives?

2. Change Permalink

By default, your blog has the URL structure /:categories/:year/:month/:day/:title. However, search engines love (and users too) concise and descriptive URLs.

Ex: is better than

Add permalink to _config.yml.

1permalink: /:title

Learn more about permalinks here.

3. Set up a custom domain

First, you have to buy a domain from a domain registrar.

After doing that, add a CNAME record in your DNS zone pointing to

Next, create a file named CNAME at the root of your site. Then, add your domain name there.

Finally, commit and push the changes. (As we updated a post).

4. Change the Jekyll Theme

Don't use common themes. Find a brand new, beautiful theme for your website. There are thousands of free and premium themes out there. Do a little search. You'll find many of them.

See how to change Jekyll Themes.


In this article, we discussed how to build a static blog with Jekyll sites. If you are a developer, the process must be a piece of cake. However, it does not take much time to set up a blog with Jekyll. And, writing and updating content is much easier. If you encounter errors while setting up, let us know below.

Thank you for reading! ✌