Ben's blog

Using Jekyll for blogging

I created a blog using Jekyll a few days ago. This is the first post on the new format. I will post content that I’ve already written over the next few weeks. In this post, I describe how I set up this blog.

For a long time, I have been looking for a convenient way to set up a site or blog. I wanted to be able to include mathematical formula’s, have a comment section, and a site that is statically generated and usable with Javascript disable (except for the comment section). I was looking for something that looks clean with minimal configuration. Using Jekyll, I was finally able to have a site that ticks all these boxes.

I usually write in StackEdit, a markdown editor. My previous workflow was to use StackEdit to export the articles to HTML. This works pretty well; I am especially fond of the clean look, and how formula’s are included as statically rendered HTML. However, there are some limitations of StackEdit: It is hard to include pictures without uploading them somewhere first, and I have to manually add a link to the new article on the overview every time I add a new article. I also wasn’t quite happy with the look of the home page, which had exactly the same look as an article (because that’s just the way that StackEdit renders to HTML).

I use a GitHub repository with GitHub Pages enabled to host my site, and this made me stumble upon Jekyll. Jekyll is a static site generator. Essentially, you write blog posts in markdown, and Jekyll uses some templates to convert it to a beautifully styled blog. Jekyll is written in Ruby, and also supports themes and plugins. I will explain here how I set up Jekyll for my blog.

GitHub Pages

Using GitHub Pages is as easy as creating a GitHub repository with the files that make up your site, going to the GitHub repository settings, and enabling GitHub pages, where you can choose the branch that the site should use.

Assuming you have a folder site that contains your site, and GitHub account username with a repository repo, you should be able to do something like

cd site
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/repo
git push -u origin master

If you succesfully pushed, the site should be available at username.github.io/repo. If the name of your repo is username.github.io, the site should become available at username.github.io. It usually takes a couple of minutes before your site is updated, and it can take a couple of hours before username.github.io redirects to username.github.io/index.html.

Installing Jekyll

You can install Jekyll by following the installation instructions for your operating system. For Arch Linux, you can install Jekyll’s dependencies with

sudo pacman -S ruby gcc make

This should also install the Ruby package manager ‘gems’ from the rubygems package, which is a dependency of the ruby package. Now, you can do

gems install jekyll

to install Jekyll. On other Linux distributions, the process is probably similar but slightly different.

Getting started with Jekyll

You can either start a new, empty blog with the default theme, or find a nice theme and clone it’s GitHub repository. I recommend that you start a new empty blog first. You only need to have some files locally, which you can delete later. So, you don’t have to put anything online to try Jekyll.

This section is written just to get you started. If you want to get more serious, read Jekyll’s documentation. I recommend you start with the quickstart guide and follow the step-by-step tutorial after that.

Starting an empty new blog

You can start a new blog with the name ‘AwesomeBlog’ with the default theme ‘minima’ by running

jekyll new AwesomeBlog

This will create a new folder named AwesomeBlog. In this folder, a new file named _config.yml will be created, which contains some configuration. Most files are not placed in this folder, but are kept in the folder which contains the defaults for that theme. To show were the theme defaults are stored, use

bundle show themename

To override settings, you can place folders and/or files with the same name in the blog folder. I recommend that you copy them from the theme folder to your blog folder, and edit them there.

You can read Jekyll’s documentation on configuration if you want to know more.

The folder _posts will contain the actual blog posts. With the default configuration, the filename of a blog post will need to start with the date in year-month-day format, and have the extension .md or .markdown (for example 2019-03-29-hello-world.md).

The file contents look something like this:

---
title:        "Blog title"
description:  "A short description of the page's content."
author:       "John Doe"
---
This is the first post on my new Jekyll blog! :)

The first section is called the YAML front matter. If the title is not specified here, the text after the date in the filename is used (dashes are replaced with spaces, and every word is capitalized). If you run jekyll serve in your sites root folder, Jekyll will start a local server, and you can view your blog by visiting http://localhost:4000 in your browser. Every time you make a change, the site will get rebuild automatically (except when the change is in _config.yml, in which case you’ll need to restart the server manually). To build a version that you can upload, run jekyll build. Jekyll will generate the HTML in a folder called _site. Note that the same folder is used when you run jekyll serve, which means that you need to run jekyll build again after you run jekyll serve.

Using an existing theme

Jekyll themes are usually kept in a GitHub repository. To use one, you simply clone the repository with git. Then, you can change the configuration, add new posts, and run jekyll serve to view the blog locally. I used the Kiko theme, and added a bar with links to various accounts on other sites, which I found in the Kiko-now theme.

Using GitHub Pages with Jekyll

In the section about GitHub Pages I suggested that you upload HTML files to the repository containing your site. Since GitHub Pages has support for Jekyll, it is also possible to make the root of your blog a repository and use this as the source for your site. GitHub then automatically builds the site for you. Note that for security reasons, Jekyll plugins are not supported if you decide to host your blog this way. This is the reason that I chose not to do this (I use a plugin to render math statically).

Math rendering

Mathematical formulas are usually specified in the form of LaTeX. We can render math either in the browser, when the site is loaded (which is called client-side), or once when we call jekyll build (which is called server side). First, I’ll explain client-side rendering with MathJax and KaTeX. Then I’ll show how you can use the jekyll-katex plugin to render math server-side.

MathJax

The easiest way to render math is by using MathJax. MathJax is a complete, but slow library for rendering LaTeX to HTML. Using MathJax is as easy as adding

<script type="text/x-mathjax-config">
	MathJax.Hub.Config({
		extensions: ["tex2jax.js"],
		jax: ["input/TeX", "output/HTML-CSS"],
		tex2jax: {
			inlineMath: [ ['$','$'], ["\(","\)"] ],
			displayMath: [ ['$$','$$'], ["\[","\]"] ],
			processEscapes: true
		},
		"HTML-CSS": { fonts: ["TeX"] }
	});
</script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"></script>

in some place so that it ends up in the <head> section of your posts. Usually, this place is it is in the <head> section in _layouts/default.html. Note that you might have to copy the _layouts folder from the path that bundle show themename returns. In the minima theme, you need to add this script to _includes/head.html (which, again, you might have to copy from the path returned by bundle show minima).

KaTeX

KaTeX is similar in spirit to MathJax. It is noticeably faster than MathJax, but less complete. Another difference is that KaTeX expects you to manually call a method for every formulla that needs to be rendered

katex.render("c = \\pm\\sqrt{a^2 + b^2}", element, { throwOnError: false });

However, you can include an auto-render script, and specify what the delimiters for rendering math should be. By default these are \\( and \\) for inline math and \\[ and \\] for math in display mode, which are different from any default, so I tend to change them so that they are the same as in MathJax. If you use the following script in the <head> section instead of the script that was used to load MathJax, everything should work fine.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.1/dist/katex.min.css" integrity="sha384-dbVIfZGuN1Yq7/1Ocstc1lUEm+AT+/rCkibIcC/OmWo5f0EA48Vf8CytHzGrSwbQ" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.1/dist/katex.min.js" integrity="sha384-2BKqo+exmr9su6dir+qCw08N2ZKRucY4PrGQPPWU1A7FtlCGjmEGFqXCv5nyM5Ij" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"></script>
<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
            delimiters: [
				{ left: '$$', right: '$$', display: true },
				{ left: '$', right: '$', display: false },
				{ left: '\[', right: '\]', display: true },
				{ left: '\(', right: '\)', display: false }
			]});
    });
</script>

The documentation is terrible. I can’t find anything about the renderMathInElement method, but this seems to work.

Server-side rendering with KaTeX

My preference was to render the math to HTML once when the site is built. This can be done with jekyll-katex, a plugin for Jekyll. The readme is excellent, so I won’t replicate the steps to get it working here.

Disqus comments

For comments, I use Disqus. If you sign up for an account and follow the installation instructions (there are instructions specific to Jekyll as well), things should work out. Alternatively, I like the guide here.