Learn & Setup Jekyll with Minimal Mistakes

In this blog post, we will understand the basic structure of Jekyll-based templates and get started with one of the most popular and feature-rich Jekyll template — Minimal Mistakes. If you haven’t already set up gh-pages repo for your new website, please follow the Part-1 of this blog here.

Jekyll (written in Ruby) is one of the most loved platforms by developers and bloggers mainly for its simplicity and the ease of getting started. Editing pages and writing blogs in Jekyll is as simple as writing on a notepad. Now, if you’re familiar with Markdown and/or HTML language, you can do a lot more! For starters, here’s a basic Markdown Cheatsheet for getting familiar.

The website on which you’re currently reading this blog was built with Jekyll by a non-web developer person, me! Therefore, if this feels daunting, please hang in there with me, and things will start to make sense.

Summary of the Part-2 guide —

1. Basic structure of Jekyll template
2. The Magic of config file
3. Using Minimal Mistakes

---

1. Basic structure of Jekyll template

A typical Jekyll template has the following files and folder and other files in the main directory.

_data, _includes, _layouts, _pages, _posts, _sass, assets, Gemfile, _config.yml

• Typically, the _data directory consists of files to control the navigation menu, authors, and other metadata-related files. The navigation menu controls what goes in your header menu.
• The _includes, _layouts, and _pages folders contain files pertaining to website format, page layout format, and the pages themselves. As we will see, these formats can be used to control the look of your website pages. The more you explore, the more you will gain familiarity with these files. This will give you control over every space on your website.
• _posts is where you’ll store your markdown blog posts. Typically, the post files start with the date followed by the blog name, for example: 2022-01-09-hello-world.md. Every post starts with metadata tags —

---
title: "Welcome to Jekyll!"
header:
 teaser: "/assets/images/500x300.png"
categories: 
 - Jekyll
tags:
 - update
---

### Here goes your main content
Hello world!

• _sass folder contains the CSS files, which mainly control the color and space formatting of your HTML files.
• assets folder is where your images folder is stored. Please note that when you want to use images in your posts, this is where all your images must be stored, and the path to your images goes like /assets/images/my_image.png. This is important because after Jekyll builds your website, the image paths are expected to have a common relative path.
• Finally, Gemfile is used to store gem requirement information for installing and building your Jekyll blog. In short, it’s an important file.

2. The Magic of _config file

Hey, but you didn’t talk about the _config.yml file? This is because the _config file calls for its separate section. This file is the heart of every Jekyll template. Depending on the quality of the template you choose, _config file alone can help you set up the majority part of your website.

If you take a look at a config file, the structure seems to be self-explanatory with tags your website name, description, social-media usernames, google-analytics, Disqus, website logo, and so on. The config list can be rich and full of features depending on your chosen template. All you need to do is fill up all the relevant details. You’ll find an explanation before each field in your config file most of the time. Therefore, while choosing your template, take a look at the config file.

Richer the config, lesser will be your programming efforts.

3. Using Minimal Mistakes

That’s a lot of theory, now let’s get our hands dirty.

Minimal Mistakes is one of my favorite Jekyll themes mainly because of its features, friendliness, and excellent documentation. It contains sample posts explaining everything you can achieve in your blogs and pages with some basic Markdown and HTML tags.

We will follow the remote theme method in this setup guide, you can also build it locally.

Step 1 — Setup Minimal Mistakes in your gh-pages:

First, start with an empty gh-pages repository named your_username.github.io. Next, add this repo to your own gh-pages repo and make these suggested changes to your Gemfile. Fork this repo to your GitHub account. We have to deal with two different repositories here because Minimal Mistakes being a large theme, is split into two separate repos. However, you’ll be only making changes to the one store in your gh-pages akayour_username.github.io.

Finally, edit your _config.yml and change remote_theme : your_username/minimal-mistakes. This will connect the two split parts of the theme.

Step 2 — Edit your _config:

Fill up all the relevant information in config file, including logo, website description, social handles, 3rd party integration API keys, and so on.

Don’t forget to add the CNAME file if you have a custom domain

Step 3 — Update your navigation bar:

Open _data/navigation.yml and make the change what you’d and wouldn’t like to see in your page header. Remember, this structure will take some time to get used to, so don’t be afraid to experiment here and there. That’s how we all learn!

Steps 4 — Publish your knowledge

Finally, start writing your blog posts inside _posts folder. You can also create new categories such as projects like here. The best place to learn and play with these features would be the official documentation.

It might have taken more than minutes, but trust me, this will all be worth your time and efforts. If you find this or my other posts helpful or have any questions, please leave comments below.

Sayonara.