Using Jekyll Scholar with Github Pages
PUBLISHED
14 JANUARY 2022
By default, Jekyll Scholar isn’t supported by Github Pages based on the list here.. This plugin is extremely useful in generating references on your posts as it allows you to place a references.bib file inside _bibliography/ in your Jekyll source code, and use liquid tags {% bibliography --cited %} to automatically generated used citations via the {% cite article_name %} tags in your post. This also allows references to be shared across posts and not have to individually rewrite references.
This other blog post covers everything, and the updated GitHub Action can be found here but I’ve personally had to make changes as I was running into errors for not following it exactly.
First you need a Docker image to build Jekyll locally and I decided not to use Martino’s Docker image as I wanted to try creating my own. Luckily it was fairly simple. My docker image was created specifically for jekyll-katex and jekyll-scholar plugins, which is available here and follow this guide.
I needed to use jekyll-katex and jekyll-scholar extensions, and so had to customize the Docker image by using my own Dockerfile publishing my own on Docker Hub.
1
2
3
docker run --rm --volume="$PWD:/srv/jekyll" \
--user $(id -u):$(id -g) \
-i evantancy/evantancy.github.io:latest jekyll build
I ran into errors where the main branch couldn’t be found, so a simple git fetch solved this. There were also permission errors for the mv command, which could be solved with sudo chown -R $USER:$USER ${{ github.workspace }}
1
2
3
4
5
6
7
8
9
10
11
run: |
...
git config --local user.name "GitHub Action"
git fetch
git checkout main
ls -Q | grep -v _site | xargs rm -rf
sudo chown -R $USER:$USER ${{ github.workspace }}
mv _site/* .
rm -rf _site
rm -rf .jekyll-cache
...
It’s a lot more to manage than simply pushing changes to your remote repository and letting GitHub take care of the building etc. By letting GitHub handle the build, you don’t need to touch Docker, GitHub Actions, but are limited to a set of plugins and specific versions. However, after a somewhat tedious setup the Jekyll plugins that can be used are no longer restricted to this list. Personally, I have just started using jekyll-katex for LaTeX, jekyll-scholar for easy referencing, and jekyll-target-blank for creating external links.