Overriding one or two layouts of a git submodule theme

When I first set this website up, I didn’t know how to override default theme layouts without editing in the theme folder itself, so I grabbed a static copy of the theme folder from GitHub. I figured this would let me make the theme edits I wanted without accidentally harming the upstream theme, or getting overwritten if I kept the theme as a git submodule and updated the theme regularly.

However, I eventually realized that it was too bothersome to try to keep the theme dependency software updated (turns out I don’t fully understand all the front-end code that Radek uses to render the aesthetics!). Too many GitHub Dependabot updates that went over my head! I decided to sync back on to Radek’s updated theme repo using a git submodule for the theme instead.

I renamed the old theme folder to remove name conflicts with the incoming updated theme, and then git submodule add-ed the hugo-theme-terminal repo into my themes folder. When I was ready to delete the old (temporarily renamed) version of the theme folder, I had to do a couple things to get git to cooperate:

1. Delete the old version of the folder, leaving only the new submodule version of the folder
2. Run git rm --cached -r themes/hugo-theme-terminal in a terminal window to stop git-tracking (“delete” in git’s eyes) the folder that is now submodule-linked. This would protect against double-uploading the submodule files to my GitHub repo.
3. Run git config --global diff.ignoreSubmodules dirty per this Stack Overflow post to get git to ignore all “dirty” untracked submodule folders (because they’re actually perfectly fine and accounted for)

Now, the theme is no longer redundantly tracked in my website repo, and every time I want to update the theme, I can use git submodule update and get any security updates taken care of as well.

Now, how to override layouts in the one or two places I might want to? Turns out this was straightforward to do all along! Per these instructions, I created a layouts folder in the root folder of the repo, the contents of which would override any files in theme/hugo-theme-terminal/layouts, as long as any file/folder names in the override layouts folder exactly matched files in the theme folder to be overridden.

For the theme edits below where I needed to create new layout pages or edit existing ones, I made copies in this theme-external layouts folder.

Making a new homepage template

Radek’s Terminal theme by default sets the homepage to be a list of blog posts. I knew that for this site, I wanted a simple splash landing page. Additionally, I still wanted to use the blog posts list layout, but as a page accessible through the menu bar.

Adding pages to the menu bar

The config.toml file, as indicated by the name, handles site-wide configuration settings. I think this may differ from Hugo theme to theme, but in the theme I selected, this file also determines which pages are linked in the main navbar. To change the organization of the menu bar, and add pages like my research and game show summaries, I copied and pasted existing menu bar subsections and changed the identifier, name, and URL arguments to match the new page files I’d created (research and game-shows respectively, in this case).

Setting public as the GitHub Pages root directory

I followed the instructions Coby Chapple’s GitHub Gist post to create the gh-pages branch of my repository with a subfolder as the root directory of the other branch. This way, I could git-track the whole directory on the master branch, editing and rendering as usual, while treating the public subfolder as the root folder of my website so everything shows up properly when someone visits in a browser.

Re-pointing my old Squarespace domain name

To hook a GitHub Pages site to a custom domain name, you have to set up two steps:

1. Tell your domain name system (DNS) provider to point your domain name to your GitHub Pages URL
2. Tell your GitHub Pages site to use a custom domain

Prism.js, and the mysterious case of pre vs code classes

The hugo-theme-lithium default theme that blogdown sets up with comes with highlight.js for code syntax highlighting. Many Hugo websites don’t involve people posting code they’ve written, so Hugo themes don’t all come with syntax highlighting Javascript plugins. When they do, though, they don’t all use the same plugin to color the code. Terminal, the theme I selected, uses Prism.js for syntax highlighting.

What these plugins do, somewhere under the hood, is look for HTML content with a specific tag. All content tagged to identify it as code gets passed through the coloring plugin, which formats the text with the right colors for function names, arguments, and such.

When blogdown knits R Markdown files to raw Markdown, and then knits those files to HTML, it detects the location of code chunks and adds the tags <pre class=r> and <code> so that the syntax highlighting plugin knows which sections are R code, and should be pre-formatted and highlighted. To embed chunks of another language, the preformatting tag can take a different class, e.g. <pre class=python>. Ideally, your code gets seamlessly colored in HTML, with the colors adapting to whatever language you’d written in. However, clearly that’s not what happened for me, because you’re reading this now.

What I discovered, after knitting my website several times and seeing that code chunks did not have highlighted text, was that blogdown was formatting the HTML tags using an outdated syntax Prism.js did not understand. blogdown was labeling knitted code chunks with the tags <pre class=r><code>. But Prism.js was expecting the tag to be a little different: <pre><code class=language-r>. The language class had moved from the <pre> tag to the <code> tag, and now had the language- prefix. (I believe that highlight.js has now updated as well to expect the language tag as <pre><code class=language-r>, but it might still be backwards compatible with blogdown’s output, thus not requiring the hacking I did. Prism.js is most definitely not backwards compatible.)

Okay, so this seemed fixable with a bit of pattern matching magic. All I had to do was string-replace all of the code chunk tags in my blog post HTMLs with the Prism.js-compatible syntax. Seems easy enough right? Well, not so fast.

Lua filters for pandoc

I learned that pandoc uses filters to apply small formatting changes. These changes are made on a special pandoc intermediate file (so, when an Rmd file is knitted, it actually goes Rmd -> md -> pandoc -> HTML). At their core, these filters allow you to apply complex string matching to edit the pandoc intermediate file, in a way such that the search-and-replace always searches in a consistent language (pandoc intermediate syntax) but can modify formatting tags that will go into a variety of languages (HTML, LaTeX, etc). You could use this to, say, replace all HTML tags matching a certain pattern with slightly modified HTML tags. This should solve my HTML code highlighting issue!

Pandoc’s filters are written in a scripting language called Lua, which I had never heard of until I started diving into this pandoc debugging issue. Lua seems really handy, but I still am no Lua expert. All I could tell was that pandoc had the ability to run extra Lua scripting files while knitting an Rmd to string-replace whatever formatting tags I wanted to replace. All I needed was a local copy of the script file.

As is usually the case with odd code issues, I wasn’t the first one to use Lua filters to fix R Markdown’s HTML syntax highlighting tags. I found that Duncan Garmonsway had implemented a local Lua filter to reformat Prism.js-compatible HTML code tags in a blogdown-based website he maintained. He himself had created an R-specific version of a-vrma’s original (pandoc-wide, not just Rmd) Lua filter to fix the same syntax highlighting issue.

I downloaded the highlight.lua file from Duncan Garmonsway’s govdown website repository and saved it into the resources folder of my own repo.

Then, to test that the filter file worked at all, I partially knitted a tester Markdown file directly from the terminal. To debug just the pandoc part, and not the R Markdown part, I created a .md file where I wrote some filler Markdown text and included a styled code chunk with a language label like ```r or ```html. Then, in terminal, I ran a version of following pandoc command to try to knit the Markdown file with the highlighting syntax Lua filter script:

(paths as always are machine-specific)

pandoc intermediate-file.md --output output-file.html --lua-filter=PATH/TO/HIGHLIGHT/FILTER.lua --no-highlight

The test worked! The knitted HTML had correctly highlighted chunks! So I went back to R Markdown and edited the _output.yml file to add the highlight.lua filtering command to the default YAML header that would run for every R Markdown in the directory. _output.yml allows you to specify default settings that would get thrown under the output: YAML header at the top of your Rmd. In this case, the pandoc_args: subheader takes a character vector of flags as they would be specified if you were calling pandoc through the terminal (as in the example code above).

For this repo, the _output.yml contains the following YAML headers:

blogdown::html_page:
  toc: true
  pandoc_args: ["--lua-filter=$HOME/Repos/personal-website/resources/highlight.lua", "--no-highlight"]

With the R Markdown pandoc settings now configured to call the highlight.lua filter script, everything SHOULD work smoothly. I crossed my fingers and ran blogdown::serve_site() to render my Rmd web pages and…

An error! “pandoc: unrecognized option”! Aaaghhhhh! Why was it running in terminal, but not through R Markdown?

Updating RStudio’s pandoc installation

This bookdown GitHub issue from 2018 revealed the solution. Pandoc was too old! But then why was it working when I tried to run the pandoc commands directly from the terminal, and failing when pandoc was run inside of RStudio?

After much digging, I discovered that I had a second, newer copy of pandoc installed with Anaconda. (Yes y’all, I installed Anaconda WAY after I started using R.) When I was calling pandoc through the terminal, it was calling the Anaconda version, which was new enough to work with Lua. However, RStudio was calling the older copy of pandoc inside of the RStudio app folder, which did not have Lua filters installed. Freaking path problems…

I manually downloaded the newest version of pandoc and copied it into the RStudio app folder to overwrite the original bundled version. It worked, and the Lua filters ran! I finally had the delicious, multi-language syntax highlighting I was originally promised.