Goals

I wanted to set up a nice-looking blog to record the documentation of the various custom systems I set up. Turns out that’s harder than it sounds, though not that hard.

I decided to do it using GitHub Pages, but using a custom theme.

0. Setup the repo

I started by forking this repo and naming the repo jgillula.github.io per the instructions.

I then followed the instructions here to set up the site. Note that in the Github Action section, in the code block for .github/workflows/github-pages.yml, you need to replace the token: $ line with token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}.

Also, since this theme didn’t automatically come with a Gemfile, I had to make one.

1. Customizations

I made a few edits to the site’s CSS in assets/css/theme.scss.

I also got pagination working, but by the time I got to write this documentation I forgot how. _includes/pagination.html is a good place to start.

Originally with this theme you could enable a table of contents for a post by setting toc: true in the front matter section of a post. I decided I’d rather always have the TOC on the side, so in _includes/sidebar.html, I added code to detect if the layout was a post or not, and show the table of contents if so.

I also wanted to automatically generate links to every header, so I changed _includes/header.html to include a slightly edited script from here to automatically insert links, and again edited the css in assets/css/theme.scss.

Last, I wanted a nice “copy” button for code blocks, so I copied some code from here into _includes/header.html and assets/css/theme.scss.

2. Update the repo

To add new posts, just copy an existing post in the _posts directory, edit it, and then push to Github. The Github action will take care of updating the blog, though it may take a minute.

If you want to see what the post will look like locally before publishing, run

bundle exec jekyll serve

in the root directory of the repo.