How to create a blog just like this one

Why create a blog in the first place

I have been thinking about opening a blog for a while but had put it off due to time limits. However, I have been working on a few projects that I think are worth sharing, and I have been learning a lot of new things that I think are worth writing about. So I decided to finally create a blog to share my thoughts and projects with the world.

I think writing and sharing your work is a great way to learn and grow. It forces you to think about your work in a different way, and to communicate your ideas in a clear and concise manner. It also allows you to get feedback from others, which can be very valuable.

If you are thinking about creating a blog, I hope this guide can help you get started.

Why Jekyll

Jekyll is a simple, blog-aware, static website generator. A static site is a website that is served to the client exactly as stored, without any server-side processing. This means that the contents of the site are not generated on the fly, but are pre-built and stored as static files on the server making it very fast and secure.

Jekyll pre-processes your markdown files and assets and then generates the final HTML files for your site. You can use liquid templates to generate HTML, and you can use Sass to generate CSS for the site. Jekyll is the engine behind GitHub Pages, so you can host your blog for free on GitHub Pages (which is what I am doing).

I first found out about Jekyll while skimming through Andrej Karpathy’s blog. In this (Karpathy, 2014) post, he explains why he migrated his blog from Wordpress to Jekyll and GitHub Pages. I was sold on the idea of a simple, fast, and free blog that I can host on GitHub so I decided to give it a try.

Ruby basics

To understand Jekyll, it is important to have a basic understanding of Ruby and its package ecosystem. As you might already know, Ruby was one of the most popular programming languages for web development in the 2000s and early 2010s. It was the language behind the Ruby on Rails framework, which was used to build many popular websites. While Ruby is still used today, but it has been overshadowed by JavaScript and Python in recent years.

Ruby libraries are called gems and are distributed through RubyGems, which is similar to npm for Node.js and pypi for Python. Jekyll is a Ruby gem, so you need to have Ruby installed on your system to use it.

Last but not least, Bundle is the environment manager for Ruby, and it is used to manage the gems that your project depends on. You can use it to install the correct version of the gems that your Jekyll site depends on, it is similar to a Python virtual environment manager like poetry.

Setting up a simple blog with Jekyll

Jekyll is a Ruby gem, so you need to have Ruby installed on your system to use it. The official documentation has a quick-start guide that you can follow to set up a simple blog with Jekyll. I will not repeat the instructions here, but I will comment on the files that are generated by the quick-start guide:

Gemfile: This file lists the gems that your Jekyll site depends on. You can add other gems to this file if you need to use them on your site. It is the equivalent of a package.json file in a Node.js project or a requirements.txt file in a Python project. If you are using GitHub Pages, you should note that only a limited set of gems are supported on GitHub Pages, check out the next section for details on how to use Jekyll with GitHub Pages.
Gemfile.lock: This file is generated when you run bundle install and it locks the versions of the gems that your site depends on. This ensures that your site will build the same way every time you run bundle install.
_config.yml: This file contains the configuration settings for your site. You can use this file to set the title of your site, the base URL, the theme, and other settings. You can also use this file to set default values for variables that you use on your templates.
about.markdown: This file stores the contents of the about page for the blog.
index.markdown: This file is an example of a markdown file that you can use to create the home page for your site.
404.html: This file is an example of a custom 404 not found page for your site.
_posts: This directory is where you store your blog posts. Each post is a markdown file with a name that follows the format YYYY-MM-DD-title.md. The date is used to sort the posts and to generate the URL for the post.

Using Jekyll with GitHub Pages

Even though Jekyll is the engine behind GitHub Pages, not every ruby gem is supported on GitHub Pages. This means that you need to be careful when adding gems to your Gemfile, since your local website might not build correctly on GitHub Pages if you use unsupported gems. You can find the list of supported gems here.

Here is the default Gemfile that is generated by the quick-start guide:

source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
#     bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
gem "jekyll", "~> 4.3.3"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
end

To make sure that this does not happen, you can use the github-pages gem. This gem is a dependency of GitHub Pages and it is updated regularly to match the version of Jekyll that is running on GitHub Pages. To do so:

Open the Gemfile file and add follow the instructions in the comments. You will need to comment out the gem "jekyll", "~> 4.3.3" line and uncomment the gem "github-pages", group: :jekyll_plugins line.
Then run bundle update and bundle install to install the github-pages gem.
If you try to launch the website with bundle exec jekyll serve you might get an error message stating that webrick is missing. To fix this, run bundle add webrick and then try to launch the website again. You can also launch the website with bundle exec jekyll serve --livereload to enable live reload. This will automatically refresh the page in your browser when you make changes to the files in your site.

Once you are happy with your local website, it is time to publish it on GitHub Pages. To do so, you need to create a new repository with a specific name following the format username.github.io. Then you need to push your website to the master branch of the repository. You can find more detailed instructions on how to do this here.

The way this works is that every time you push to the master branch of the repository, GitHub Pages will use a CD pipeline to automatically build your website using Jekyll and serve it.

If you want to use a custom domain name, you will need to buy a domain name (I use porkbun) and then follow these instructions to set up everything.

Why ai-folio

While the default Jekyll theme is good enough for a simple blog, I wanted to have a more features and a modern look without having build everything from scratch so I decided to look for a Jekyll theme that I could use as a starting point. After some research, I found the ai-folio theme, which is designed for academic blogs, lab pages and course websites. I liked the clean and modern design of the theme, and I thought it would be a good starting point for my blog. I also liked that it comes with a docker-compose file that makes the development process easier to manage.

The theme comes with a lot of features available out of the box, some of them only need minor configurations to work. Some of my favourire are:

Easily change between light and dark mode with a switch in the top right corner
Jupyter notebook support.
MathJax support.
Chartjs and echarts charts
Mermaid diagrams (check them out here, they are really cool)
Support for disqus comments
Google Analytics support

Not everything was perfect with the stock ai-folio theme. For example, it can be overwhelming to understand all of the features that come with the theme, and removing the things that you do not need is very time consuming. I also do not like the way the folders are organized in the assets directory by default. I would rather have all the resources organized in a /assets/{page-type}/{page-name}/{resource-type}/{file-name} structure, rather than the default /assets/{resource-type}/{subfolder-name}/{file-name} structure. This way, I can easily find all the resources that are related to a specific page in the same directory. Neither do I like the default page footer for the theme, which I spent some time customizing.

Nevertheless, I think that the theme is a good starting point for a blog, and I am happy with the results.

Conclusion

I hope that this guide has been helpful for you and that you now have a better understanding of how to create a blog with Jekyll, ai-folio, and GitHub Pages. If you have any questions or comments, feel free to reach out to me on my socials or by email.