Lots of people, both in the academic and software communities, have personal websites. Building one with today’s frameworks is easier than perhaps at any point in history, yet many people still have websites consisting of an index file inside of a folder hosted by some outdated service. In this post, I describe how this website is built, showcasing software used to make all aspects of developing and maintaining a blog intuitive and easy.

Using modern tools is worthwhile: sites that are minimally styled tend to display tiny fonts on mobile devices, making them inconvenient for readers. They are also inconvenient for authors: if updating a website is cumbersome, then it is more likely to never be updated and contain out-of-date information. These issues are entirely avoidable, without spending time or paying anyone. Let’s see how.

Building the site with Jekyll

This is a static website: its HTML code is generated when it is created, not when the user opens it. The code is generated by a static site generator called Jekyll,¹ written in Ruby. We can think of Jekyll as a magic box that takes in a directory of files, and outputs a fancy formatted website. Let’s take a look at a minimal example directory.

.
├── _config.yml
├── _posts
|   └── 2018-09-15-building-this-website.md
├─ about.md
└─ index.md

Here, the file _config.yml is Jekyll’s configuration file. Jekyll is blog-aware: the _posts directory is where it expects to find blog posts. The remaining files are Markdown text files to be used for generating individual pages and blog posts. Let’s examine a fairly minimal configuration file.

title: My new website
description: A really cool website

This defines the title, description, and author fields which will be used by the theme. Now, let’s see what a minimal post such as 2018-09-15-building-this-website.md might look like.

---
layout: post
title: Building this website
author: Example Author
---

# Welcome to the new post

Here's a new post about how the website is built!

The section surrounded by --- at the top is called the post’s front matter: it tells Jekyll that the post’s HTML should be generated using the post layout, and that its title is Building this website. The rest of the file is just Markdown text: # Welcome to my new post will render as an HTML header that says Welcome to my new post, and Here's a new post about how the website is built! will render as a line of text.

To have Jekyll generate the site, we run it, by typing jekyll serve into a terminal window. This starts up a web server, and we can view our page by navigating to localhost:4000. We get a fully functional website, containing an index page, an about page, and the post. Jekyll automatically inserts the correct author and date into the post. Jekyll’s default theme includes a homepage layout, and Jekyll will automatically create a link to the blog post from there. At the end of this process, we have a working site—all without ever touching any HTML code.

Hosting the site with GitHub Pages

In order to have the website be publicly visible, we need to host it somewhere. It used to be that the easiest way to do so was to acquire a server and copy files onto it. Today, we can instead use GitHub Pages,² which greatly simplifies this process, hosts our website, and costs absolutely nothing.

GitHub Pages works very simply. First, the user creates a repository using the version control software Git and hosts it for free on GitHub. Then, every time files are committed and pushed to the Git repository, GitHub automatically runs Jekyll to build and publish the site. That’s it!

This process is exceedingly simple and tends to just work. We don’t need to do anything other than keep the website in a Git repository, which is good practice regardless, as it allows us to maintain version history and undo changes that broke something if need be. By default, GitHub will host the site at {username}.github.io, but it’s possible to buy a custom domain from any provider for a few dollars per year and configure it easily. The domain name is the only thing I pay for: everything else is completely free.

Responsive design with Bootstrap and the Minima Reboot theme

Jekyll ships with a small number of built-in themes, and allows users to easily select other ones. Its default theme, Minima³, is very good. It is well-designed, its style is simple but modern, and it includes a navigation menu for mobile devices that have a narrow screen width. Unfortunately, it also renders narrow pages on large desktop screens, and making custom pages with responsive design elements—parts of the website that render differently on mobile devices compared to desktops—is cumbersome.

When first creating this blog, I wanted to do better, and to learn a bit of web development, so I wrote my own theme called Minima Reboot⁴—named so because it’s essentially a rewrite of Minima. The theme is enabled by adding the following line to _config.yml.

remote_theme: aterenin/minima-reboot

The main functional difference between Minima and Minima Reboot is that the latter is written using the Bootstrap⁵ frontend framework. Bootstrap makes it easy to design responsive websites that render the same on all recent browsers—a task that can be rather difficult because older browsers, especially those made by Microsoft, do not always follow web standards correctly. The technical details are out of scope of this post, but for those interested Minima Reboot’s code can be found in its GitHub repository.

This site has a few additional customizations on top of the theme, such as removing the footer and making the color of hyperlinks less bright compared to Bootstrap’s default. It also uses the Open Sans font for headers, loading it in a browser-consistent way using the Google Fonts framework.

Typesetting mathematics with KaTeX

This blog is, to a large degree, about mathematics. Hence, it includes mathematical equations that need to be rendered and displayed. The most popular way to do this—used on websites such as arXiv and Stack Overflow—is using a JavaScript package called MathJax. MathJax works and is very popular, but it’s big, complicated, and slow—so, this blog uses a newer package called KaTeX.⁶ To load it, we simply add a <script> element into the <head> element of our website, as described in the package’s documentation.

By default, KaTeX and MathJax use the \(, \) delimiters for inline math, and the $ delimiters for display-style math. I prefer to instead use $ for inline math and \[, \] for display-style math, so I override the default configuration to use these instead.⁷ Note that since the \ character is not escaped, this means that my display-style delimiters are \[,\] in Markdown, but [,] in HTML. I also use a variety of custom macros and aliases designed to make my LaTeX more readable, which both packages allow me to define. Therefore, I can write e^{2\pi i} - 1 = 0 to get $e^{2\pi i} - 1 = 0$, and can write

$
\int_{\mathbb{R}} \frac{1}{\sqrt{2\pi\sigma^2}} \exp\left(\frac{(x-\mu)^2}{-2\sigma^2}\right) \mathrm{d} x = 1.
$

to get the equation

$$\int_{\mathbb{R}} \frac{1}{\sqrt{2\pi\sigma^2}} \exp\left(\frac{(x-\mu)^2}{-2\sigma^2}\right) \mathrm{d} x = 1.$$

Generally, these packages work seamlessly. However, sometimes Kramdown, the Markdown preprocessor used by Jekyll, interprets LaTeX code as something other than text. In these situations, it can insert things into the LaTeX code that KaTeX and MathJax don’t understand—this includes <br> elements which interrupt processing of multi-line equations. This can be avoided by adding the HTML tag <p> around the relevant LaTeX code, which ensures that Kramdown treats it as raw HTML and doesn’t modify it.

At present, there is no good way of making either KaTeX or MathJax responsive. This means that large equations will occasionally go off-screen for users viewing the site on mobile devices. This isn’t ideal, so hopefully one day there will be software that lets us avoid it.

Concluding Remarks

Building a personal website is easier than ever using modern technology. Jekyll makes it easy to build a site, GitHub Pages makes it easy to host it, and tools like as Bootstrap make it easy to create a theme that looks good on all modern browsers, desktops, and mobile devices. Modern mathematical typesetting packages make it just as easy to display high-quality equations on the web as when using LaTeX to typeset a document.

Given my interest in statistical theory, I find the format offered by a blog to be incredibly useful. In my time practicing statistics, I have come across ideas that were worth communicating to other researchers, but too simple to write a paper about, or already published but using arcane notation difficult to understand. A blog post provides a wonderful way to communicate these ideas—it is more time-efficient to write a post once and refer people to it, rather than re-derive the same idea repeatedly when it comes up in discussion. I hope that this post showcases how easy building such a platform is in today’s world.

References