Migrating to Hugo + blogdown

1. The ability to write blog posts in R Markdown

This might seem like an oddly specific need, so context is probably helpful. For the past two years, I’ve had the fortune of co-teaching a third year R course called Quantitative Methods in R for Biology with the EEB department here at U of T. The lecture material is developed entirely in R Markdown and released on the course website for students to use as reference in class, since all material is live-coded following the teaching model employed by The Carpentries.

The course website, developed primarily by my wonderful friend and colleague Luke Johnston, renders these R Markdown lectures beautifully and generates clean HTML pages on the website. Working with this website made me realize the added utility the Rmd format offers in writing technical/scientific documents in general, and I realized that that was something I was just not going to get out of Jekyll.

l = [1, 2, 3]
for i, num in enumerate(l):
  print('currently at number {}'.format(num))

## currently at number 1
## currently at number 2
## currently at number 3

for i in {1..5}; do echo $i; done

## 1
## 2
## 3
## 4
## 5

library(magrittr)
library(broom)
mtcars %>% 
  lm(mpg ~ wt, data = .) %>% 
  tidy()

## # A tibble: 2 x 5
##   term        estimate std.error statistic  p.value
##   <chr>          <dbl>     <dbl>     <dbl>    <dbl>
## 1 (Intercept)    37.3      1.88      19.9  8.24e-19
## 2 wt             -5.34     0.559     -9.56 1.29e-10

2. LaTeX math mode support in blog posts

While I admittedly still feel like I didn’t poke and prod at Jekyll enough to make this work, I really, really wanted some form of math mode support on my website. LaTeX (via Overleaf) is my primary writing tool, and I’ve grown very accustomed to using math mode to efficiently write out mathematical expressions.

On our EEB313 course website, anything written in math mode in a lecture’s Rmd renders perfectly on the website (see this fantastic lecture on mathematical modelling by Amber Gigi Hoi and Zoe Humphries, who I was fortunate to teach the course with this year). This was something I really wanted for myself; on my original website, writing out population genetic statistics such as \(\theta_{\pi}\) and \(F_{ST}\) required copy and pasting in special characters and using HTML tags like <sub> for subscripts. Really, really not fun.

In retrospect, given what I had to do to enable math mode for my Hugo website (more on that below) I could have probably done the same for my earlier website, so I don’t want to knock the latter at all for this point. But it does feel good to be able to write math right alongside executable code chunks!

3. Doing everything from RStudio

If you’ve ever had the misfortune of asking me about my long-winded opinions on IDEs and such, you’ll know I’d generally be hard-pressed to name anything that I believe beats the simple efficiency of vim and tmux – and thus refuse to use anything else. The only exception to that remains RStudio, which not only does every single thing right, but is also maintained by an excellent team that is constantly adding relevant and useful features.

I particularly love RStudio’s projects feature, with also integrates beautifully with Git/GitHub and keeps everything nice and self-contained. The prospect of maintaining the many disparate components of a website (blog posts, about/CV pages, layouts, etc) alongside added functionality from blogdown (widgets for creating new posts, inserting images, etc) all within a single RStudio project was, naturally, pretty appealing.

Hugo’s directory structure

Hugo’s directory structure might also be a bit strange to newcomers, though I found this blog post to be quite helpful in demystifying why it is the way it is. Another good rundown is naturally found in the blogdown book, in section 2.5.

I won’t recap the post/section, but here are some key things to keep in mind – some of which I made the mistake of discovering via slow and somewhat frustrating trial and error out of some weird initial need to just figure this out on my own without resorting to the reference material.

1. The website is rendered from the public/ directory.

• A corollary to this is that public/ should be treated as read-only.

• Of course, you’re able to edit any file in public to your heart’s content. But know that every single time your site is regenerated (which happens after even the smallest changes) whatever edits you directly made in public will be overwritten.

• Basically - do not even bother entering public except for when you’re pushing the website to GitHub for deployment (more on that below). All the action happens in other directories/files.

2. Your layouts/ and static/ directories will most likely be empty at first.

• Why does this matter? Well, Hugo uses the templates in layouts/ to render the markdown files in your content/ directory. Can’t do much of that if there are no layouts.

• However, if your theme is anything like mine, there ought to be a themes/ directory containing its own layouts/. Copy everything in the latter former into the base layouts/ folder. Same goes for static/.

• I don’t know if this is standard practice, but it worked for me, and only needs to be done once, really.

Two ways to get your site running locally

The blogdown book recommends using blogdown::serve_site to create a local server, but I’ve found that running hugo server in Bash while in the root directory of your site does the same thing. The advantage of the latter is that it’ll reload when you make purely cosmetic changes, which I found useful when initially making some sweeping design edits. Conversely, I found serve_site didn’t always respond to those changes, for whatever reason. This may be one of those (frequent) instances where I’m just doing something terribly wrong, so your mileage may vary.

One clear difference between the two (and one I’m actually quite sure of!) is that if you’re editing an Rmd file, a server via hugo server will not dynamically update the post. This is because as far as I can tell, the Rmd files are not rendered by Hugo, and only serve_site actually looks for changes in your Rmd files before re-rendering any changed files as html. This makes intuitive sense to me, since hugo isn’t explicitly built to pull up an R kernel and selectively run chunks of code in a text file before rendering as HTML, whereas blogdown is all about compiling those Rmd files.

Finally – and this isn’t explicitly about getting a local server going, but has been helpful – running either of blogdown::build_site in R or just hugo in Bash while in your root dir will make Hugo rebuild your site. Useful in a pinch, and my goodness is it fast.

Adding your own parameters

undergrad = true

    <h2>Undergraduate Research</h2>
    <section>
        <div class="portfolio_content">
            <hr class="divider">
            {{ range (where .Data.Pages "Params.undergrad" "==" true).ByDate.Reverse }}
            <div class="row">
                <div class="col-md-4 col-sm-4 col-xs-12" href="{{ .Params.link }}"
                    target="_blank" rel="noopener noreferrer">

<p>I am a chunk of stuff you want to have the option of hiding globally.</p>

showchunk = false

{{ if .Site.Params.showchunk }}
  <p>I am a chunk of stuff you want to have the option of hiding globally.</p>
{{ end }}

Math mode (MathJax) support

So, some not great news – most Hugo themes don’t natively include MathJax support, which means that writing, say, the expected genetic diversity in a population tends to render like this:

\[ \theta = 4N_{e}\mu \]

instead of \(\theta = 4N_{e}\mu\). Fixing this was a bit frustrating, but the solution I eventually found (via this great blog post) boiled down to:

1. In layouts/partials, create a file called mathjax_support.html containing the second snippet of code in the above blog post.

2. The post above recommends including the file in header.html or footer.html. Maybe it’s my theme, but I had little success with either. In my case, it was adding it to layouts/partials/page-single/content.html that did the trick. By ‘include’, I mean add the following snippet:

{{ include mathjax_support.html }}

In line with the tip above about adding your own parameters, I nested this within a parameter I added:

  <div class="post">
    {{ if .Site.Params.math }}
      {{ partial "mathjax-support.html" }}
    {{ end }}
    {{ .Content }}
  </div>

This way, I can set math = false in config.toml if needed.

Note that the hugo-academic theme comes with MathJax support out the box, and is generally a great theme to use if you’re an academic. “But you’re an academic and didn’t use it,” I hear you cry, and you’re right – but like I said earlier, I was very adamant about having a nice looking sidebar.

Pushing to GitHub

This is explained in the blogdown book (section 3.3) but I completely missed it at first, as expected. The takeaway is this: When pushing your website to GitHub, init your repo in public/, not in your website’s root. Commit everything in public/, push, and render with GitHub Pages; public/ should contain everything GitHub Pages needs to put the front-end together.

You may want to commit your whole site directory for posterity, but creating a Git repo that contains a subfolder which is itself a separate Git repo is a much murkier prospect than it sounds: if you’re currently in public/ and run a Git command, what’s stopping Git from thinking you’re in a subfolder of the root directory and acting accordingly? Although workarounds are possible, I just went with the following archival method:

1. Run git init in the root dir.
2. Commit and push to GitHub.
3. rm -rf the .git folder, essentially un-making this directory as a repo.

It’s an ugly workaround, but it essentially creates a time capsule on GitHub of what the rest of your site – config.toml, your layouts and static folders, etc – looks like. I figured it’s unlikely I’ll make many major changes to it, so this at the very least means that my site code lives outside of just my computer.

If you’d like to go the whole nine yards with maintaining nested Git repos, the method is laid out quite nicely near the bottom of this blog post.