Created by potrace 1.14, written by Peter Selinger 2001-2017 Thomas T Burgess's Blog

Blog setup

 
  • Jun 12, 2021

This blog is built with Jekyll and the TeXt theme and hosted for free on GitHub. The site is generated from markdown sources automatically on every push to the repository.

It’s easy to have a similar setup in GitLab, but I wanted to try the GitHub pages approach. Finding and configuring a suitable theme was more challenging than getting a blog up and running. The theme was the first pretty theme I found supporting Mermaid diagrams, math with MathJax maths, and syntax highlighting out of the box. I’ll try to revisit this post as the blog matures.

Getting the blog up and running

I’m using the Ruby Gem method to get my theme working. When writing a post, or testing modifications, I run Jekyll locally before pushing it to GitHub. Posts added to _drafts/ will not be published when pushing, which is great when writing longer posts. To serve the site including drafts locally to the default http://127.0.0.1:4000, I run

$ bundle exec jekyll serve --drafts

The local server rebuilds the site when the source is modified (with the notable exception of _config.yml). Not only does this cut on waiting for GitHub to build the site, but it also allows me to spot mistakes before publishing.

Customization

I enabled a few options:

and made some additions:

  • Left aligned, indented equations by adding displayAlign: "left", displayIndent: "2em" to _config in _includes/markdown-enhancements/mathjax.
  • Support comments through utterances following the example in this very helpful gist
  • Collapsible content containers through a details tag snippet
    • Not working with code block content :(
  • Included jekyll-figure plugin to get pictures with figure and figurecaption tags.
  • Included osano cookie consent following the approach of www.chuvisco.me
  • Added jekyll-seo-tag for open graph previews

GitHub pages annoyances

  • GitHub pages doesn’t like the theme: pointing to an unsupported theme in _config.yml. I got warnings with every build (that otherwise actually worked). Changing this to remote-theme: makes the builds warning-free.
  • GitHub pages runs in safe mode, and doesn’t support most plugins (such as the figure and details plugins that I use). This can be circumvented by building handy GitHub action jekyll-deploy-action . The trickiest part was to change master to main in the yml, and adding a repository secret for repo access. This fix likely fixes the first annoyance, but it still works with remote-theme, so I’ll leave it like it is.

Header photo by Ville Palmu on Unsplash

Search