Add Bibliography Using Jekyll Plugin
Use Jekyll-Scholar
plugin to enable citation and add bibliography.
Github Pages doesn’t support the plugin. Two options provide a workaround:
-
Change between two branches of your site repository.
-
Build your site locally and push the results to the
source
branch. This is where you keep your entire project, e.g., sources, configuration and plugins, where you make changes and build your site locally._site
folder should be in the.gitignore
. It contains Jekyll compiled HTML fies. Once build (locally), these files can be uploaded directly to a server, e.g., GitHub Pages, for hosting.
master
orgh-pages
branch. This is where GitHub Pages are deployed. Consists solely of the compiled sites which GitHub Pages can use directly.- Create a
_nojekyll
file to tell GitHub Pages not to run Jekyll each time you push things. This is very important if you have directories beginning with_
since they have a special treatment with Jekyll (they are not deployed on the Web site). -
Meanwhile, in the
_config.yml
of thesource
branch, under theinclude
key, we need to add- .nojekyll
. - Note: It is recommended to change your default branch to
source
. Optionally, you can make thesource
branch protected to prevent it from being accidently deleted or overriden.
-
-
Alternatively, you can use a Github Actions called jekyll-action to deploy your site to Github Pages.
This saves you time to manage different branches every time you make a change in your repo.
Building and deployment is done through Github Actions automatically. I would recommend this approach if you don’t mind waiting because it takes much longer time for GitHub Pages to build than does locally.
It takes about 4 minutes for GitHub Pages to finish building and deployment.
You only need to manage your remote Github Page repository. Github Actions will deploy your website automatically. Using the following codes to push your local changes to remote:
git add . git commit -m "post update" git push
Combinging multiple cmds using
&&
:git add . && git commit -m "post update" && git push
&&
is conditionally run. The following cmd runs only if the previous cmd is successful.
Installation
In Gemfile
, add gem 'jekyll-scholar'
.
Create a _bibliography
directory to sotre your bibliography .bib
files. The _
in the directory name means that Jekyll will not copy it in the generated site (_site
by default). If you want that your bibliography file is visible to your site visitors, then you should take this into account and, e.g., store the file in a bibliography
directory instead.
1. Use GitHub Actions to build and deploy GitHub Pages site
For security reasons, only a limited number of third-party plugins are supported by the GitHub Pages automated build pipeline using the default 'Deploy from a branch'
method. It is possible, however, to use GitHub’s continuous integration and continuous delivery (CI/CD) platform, Github Actions, and create a custom workflow that installs any jekyll plugin. This is actually very easy to do from your GitHub Pages repository page:
- Open the
Settings
–>Pages
tab - Under
'Build and Deployment'
, change the'Source'
from'Deploy from a branch'
to'GitHub Actions'
- Add the suggested workflow yaml file (saved under
.github/workflows
)
You can see my final workflow file here.
Note: if you have a Gemfile.lock
file committed to your repo then it may cause issues: add it to .gitignore
and remove it from your git cache (git rm --cache Gemfile.lock
)
2. Add the jekyll-scholar plugin
This is also straightforward:
- Add
gem "jekyll-scholar", group: :jekyll_plugins
to yourGemfile
(you can see mine here) - Add
- jekyll-scholar
to your_config.yml
(see mine here)
3. Downgrade ruby
Ideally, the two steps above would be all that is needed to get up and running with jekyll-scholar on GitHub Pages, but when I tried adding a citation and building my site locally I got the error message Liquid Exception: tried to create Proc object without a block
.
After a lot of googling I landed on the most likely source of the problem being incompatible ruby versions between github-pages and jekyll-scholar. I have not spent a lot of time trying to dig into this to figure out why it is an issue, or if there is a better way to solve it, but downgrading ruby from 3.1.2
to 2.7.2
solved the problem and so this is what I am doing for now.
Downgrade ruby locally
- Install older ruby version locally using chruby (
ruby-install 2.7.2
) - Restart your terminal
- Select older ruby version with
chruby 2.7.2
- Re-run
bundle install
to update gems - Run
bundle exec jekyll serve
to validate fix
Downgrade ruby in build pipeline
- Add a
.ruby-version
file to the root of your repo and specify ruby version2.7.2
- Remove the ruby version line from the
jekyll.yml
workflow
Configuration
You can configure the way Jekyll-Scholar works using your _config.yml
configuration file. The default is (see here for the meaning of the options):
scholar:
style: apa
locale: en
sort_by: none
order: ascending
group_by: none
group_order: ascending
source: ./_bibliography
bibliography: references.bib
bibliography_template: ""
replace_strings: true
join_strings: true
use_raw_bibtex_entry: false
details_dir: bibliography
details_layout: bibtex.html
details_link: Details
query: "@*"
Citation
Use the following code to add citation. cite
tag with the appropriate key of the item you want to cite.
Use this to add bibliography. The cited
option includes only those entries you cited on the page.
Special thanks to the tutorials in the blogs from (Danks, 2022) and (Poizat, 2016).
This blog is build on their original contents.
References
- Wallace, C. J. J., & Joshi, M. (2018). Comparison of land-ocean warming ratios in updated observed records and CMIP5 climate models Comparison of land-ocean warming ratios in updated observed records and CMIP5 climate models. Environmental Research Letters, 13, 114011. https://doi.org/10.1088/1748-9326/aae46f
- Danks, G. (2022). How to use jekyll-scholar with GitHub Pages. https://open-research.gemmadanks.com/tutorials/how-to-use-jekyll-scholar-with-github-pages/
- Poizat, P. (2016). Jekyll and BibTeX. https://pages.lip6.fr/Pascal.Poizat/blog/posts/2016/02/01/jekyll-and-bibtex/#: :text=You%20can%20use%20a%20_bibliography,site%20(%20_site%20by%20default).