Generating a Static Site with Jekyll

Published on 06 Jan 2022
Written by Pranav Chakkarwar
5 minutes to read

Jekyll is a static site generator

A static site generator creates a static HTML website from a template and raw data. In essence, it automates the job of generating and maintaining individual HTML pages and prepares them for serving to users ahead of time. A static site is ideal for something like a blog, where the material doesn’t need to be updated frequently. We can use a content delivery network to cache the site, thus storing a copy of it on hundreds of servers around the world. The CDN can then offer the site to any user from the server that is closest to them. This helps us save money on servers while allowing users to access the site faster.

Jekyll is my choice because it claims to be “blog-aware”, offering features that will make it easier for us to maintain our code and keep the blog running smoothly. It also offers hundreds of community-created plugins, including a feed generator, a sitemap generator, an admin panel, among others. I assume you have some basic knowledge of HTML, CSS, and JS as I cannot cover that here.

Create a new site with jekyll

To begin, install jekyll for your operating system.
Following that, we’ll create a basic Jekyll structure.
Create a new folder and open it in VS Codium.
Ctrl+Shift+’ opens a terminal in Visual Studio.
Run jekyll new-theme [Replace this with whatever name you want] to generate a new site in the current folder.
You should now notice some generated files and directories in your folder.

Here are some important ones.

_includes
_layouts
_Gemfile
_config.yml

What are these files and folders?

The key folder to organize your site is _layouts. This folder contains a default.html file. The default file’s HTML structure will be used by jekyll to produce all the site’s pages. The structure of all your blog post pages can be defined using a post.html file, etc.
You can write short bits of code in the _includes folder that you can place on different pages of your site. For example, an HTML file that contains the navbar’s code can be included in the default layout, ensuring it appears on all of your site’s pages. The site’s post.html can be included with an _includes file for the comment box which will only appear on the pages of your blog entries.
Jekyll runs on ruby, and all the plugins that you install for jekyll are ruby gems. What are gems? Let’s ignore for now. You can include gems using the Gemfile that was generated with the site. We will come back to this file when we install some plugins.
The file _config.yml is crucial because it contains the site’s metadata like, Name of the site, URL, author, domain, schema site category, social network links or other static data. It can be used to exclude or include files, change plugin settings or control the use of plugins. You can use your Gemfile to install dozens of plugins, but ask jekyll to use only a few of them using the config file. A file or folder whose name starts with a fullstop or underscore is excluded from the final site, but the config file can override this too. Ultimately, use the config file if you want to tweak something.

Create some for pages for your blog

My blog features an index.html page with information about me and the latest blog entries, a blog page with all the posts, a contribute page where you may support my selfless work, a contact page with my end-to-end encrypted contact form, and a search page to search through all the published articles. Once your site is built, you can use the name of the file to visit these pages.

You’re free to make as many of these files as you’d like.

index.html
contact.html
contribute.html
etc

Each page will use the data defined in default.html of the _layouts folder, unless you specify otherwise. Jekyll uses YAML to customize the title, description, meta image, layout, and any other metadata for each of all pages. An example YAML of my index.html page is shown below.

---
title: Pranav Chakkarwar
description: I'm a minimalist writing on privacy...
layout: default
image: /images/metaimg.webp
---

To make a page available at a different URL than its file’s name, use permalink in your YAML. The YAML below will make a page available at example.com/custom-url, regardless of the page’s name.

---
title: A new page
description: Just a page
layout: default
image: /images/image-name.webp
permalink: custom-url
---

Finally, build your website

To build your site jekyll uses some commands that must be typed into the terminal of the folder containing your website. The jekyll build command will build your site using the layouts, config.yml customizations, YAML in individual pages, and export it to the _site folder. You can serve the _site folder locally using the jekyll serve command, and your site will be available at localhost:4000 through your browser.

This _site folder contains all the files you’ll need to launch your website using a CDN, like Netlify. There is, however, more work to be done ;)