Problem 1: MathJax

One of the things I wanted to write about involved math equations, so it was important that I could render them. To do this in Jekyll, you need to add MathJax. This isn’t so difficult in theory, provided that you also use the correct host. My math equations did display as expected… for the most part.

The main problem I faced was that I couldn’t get \begin{align} to work correctly. After some Googling, I found out that there are basically two solutions. The first solution is that I can enclose \begin{align} in a math environment with $$. This is the preferable and more stable solution since I already write my equations in this format, but mysteriously, my equations don’t appear on the html page whenever I combine $$ and \begin{align} together.¹

The second solution is that I replace all my double backslashes \\ with \\\\. This is not ideal, but maybe doable if I only have to convert every once in a while for the occasional post with math equations. Yet crazily enough, this solution only worked if I copied the backslashes directly from the stackexchange solution and did not work if I typed out the backslashes myself (?!). After some futile exercises in manually copying tiny string fragments to figure out what was going on, I decided to drop the issue for the moment.

I was just going to assume, for now, that I could render math equations correctly – which at this point, I technically can through the cumbersome practice of copying backslashes from stackexchange. Assuming that, how was I going to integrate my blog into my website? As it turned out, this was also a big problem.

Problem 2: Blog Layout and Pagination

The problem with most Jekyll (and Hugo) themes is that they are either designed primarily for blogs or they are not. It’s very rare for a theme to give equal attention to both the “regular” website components and the blog. For example, the theme I am using for my main website (simplest) is a blog-oriented theme. It displays the blog posts on the front page as snippets with pagination. But let’s say I want to have my blog posts on a subpage instead of the main index page. It turns out that pagination only works in your index.html file. In other words, I can’t just copy the original blog section on index.html and move it over to blog.html because pagination will no longer work. There are some potential solutions, like jekyll-paginate-v2. But since my theme was designed to use the original jekyll-paginate, to get jekyll-paginate-v2 to work, I would need to update several things. Which brings me to the third problem.

Problem 3: Jekyll Dependencies

In my experience, the worst thing about using Jekyll are the dependencies. Every so often, GitHub prompts me to update dependencies for my website due to security alerts, which I more or less understand as “you need to update your Ruby gems.” I’m still not sure what a Ruby gem is (but I assume it’s analogous to an R package?), so every time I’m forced to do this, I’m stumbling around like a lost child, randomly inserting and deleting things in my Gemfile according to some stranger’s directions on Google,² not knowing what I’m doing, hoping that it’ll just magically work. Naturally, it doesn’t for my jekyll-paginate-v2 experiment.

Solution: Hugo + Blogdown!

At this point, I was pretty convinced that getting my blog to work properly on my website in a reasonable amount of time was not going to happen with Jekyll. So I decided to give it a go with Hugo and blogdown, an R package made by the amazing Yihui Xie. With blogdown, I didn’t need to learn how to use Hugo and start from scratch. I could just work in the familiar environment of RStudio. Hugo + blogdown solved all three of my problems:

1. MathJax: The official documentation for blogdown was thankfully quite clear about how to set up MathJax. Long story short, it’s already a part of the default hugo-lithium theme made by Yihui, but it’s easy enough to include MathJax on any theme you choose.³
2. Blog Layout: Since I wasn’t trying to integrate my blog directly into my website anymore, I could choose any theme that supported a nice layout solely for my blog.
3. Jekyll Dependencies: Hugo has the advantage of being a single binary without dependencies.⁴ Furthermore, Hugo is supposed to be vastly faster at site generation than Jekyll. I haven’t really noticed the speed of Jekyll for my website, which only has a few pages, but I might if I start writing lots of blog posts.

Admittedly, it still took me a second to get set up with blogdown (~2 hours?). One reason was my reluctance to use Netlify, despite multiple endorsements in the blogdown tutorial, because I was already accustomed to using GitHub pages. However, the problem is that GitHub pages doesn’t support Hugo, so I had to look for how to make it work. Then in the midst of Googling for solutions, I stumbled upon someone’s resounding endorsement of how Netlify was “so easy to use it should be illegal”⁵ and I thought OK, maybe I should stop being so stubborn. I’m happy to announce that the rumors are true – Netlify is very easy to use! You can connect it to your github repo and get a site set up in maybe 5 minutes.

Finally, it was a matter of linking Netlify to my custom subdomain, choosing a theme, spending way too long tinkering with font colors, and voila! My blog has been created!