Andreas Schuster

Andreas Schuster

Install And Use Jekyll-Scholar

Updated: 3 minute read

Background/Problem

I wanted to be able to add citations on websites that are generated with Jekyll [1]. The resulting citations should look like in academic publications and a corresponding bibliography should be generated as well. Also, the system to manage the references should be based on .bib or .bibtex files.

Solution

I found a Jekyll plugin (Jekyll-Scholar) that serve exactly my purpose. Jekyll-Scholar is a Jekyll plugin that allows you to cite references from bib(la)tex files. It creates the citation in the text and renders the bibliography. The associated github repository can be found here [2]. The documentation on the website is pretty good. I still thought, that I would document my setup a little bit.

Installation

First, add the following line into the plugin section of the Gemfile of your jekyll project:

gem "jekyll-scholar"

After that, stop the Jekyll server and execute the following command from inside your Jekyll project folder. This will install the Jekyll-Scholar gem if it doesn’t jet exist on your system.

bundle install

This should be it for the installation. In case the gems

  • citeproc-ruby
  • csl-styles
  • bibtex-ruby

are not installed on your system, you have to install them as well. They are required by Jekyll-Scholar. To do so run:

[sudo] gem install citeproc-ruby
[sudo] gem install csl-styles
[sudo] gem install bibtex-ruby

On my system they were already installed. I have no idea why. Anyways this caused an error message when I tried to install them again. I think it was citeproc-ruby that issued the message, but I’m not sure.

Usage

Add the following lines to the \_config.yml file in your jekyll project and adjust them to your needs.

# Jekyll-Scholar Settings
scholar:
    style: ieee
    locale: en
    source: ./_bibliography
    bibliography: literature_biblatex.bib

Here is a description of the configuration options. For my first test I tried to use the mla style, which did not work. This was because it was not installed in ~/.rvm/gems/ruby-2.4.1/gems/csl-styles-1.0.1.9/vendor/styles. This directory is probable different on your system. Since I prefere numbered citations anyways, I switched to the ieee style. At least for now.

Now you can add citations to your posts by adding

{% cite [BIBTEX_KEY] %}

in the text at the location where you want the citation to appear. Replaced [BIBTEX_KEY] with the key of the reference you want to cite that is saved in your bib(la)tex file.

At the following line to the end of your post to generate the bibliography.

{% bibliography -cited_in_order %}

Without the option -cited\_in\_order Jekyll-Scholar adds all the references in your bib file. The option -cited only adds the references that are acctually used in the text. -cited\_in\_order makes sure the references appear in the order that they are used in in the text. Otherwise Jekyll-Scholar would sort them according to your Jekyll-Scholar configuration.

One problem that exists with numbered reference styles is, that in the bibliography two numbers are added: one, because Jekyll generates a numbered list of the references, and one, because the style adds the number that is used in the text. To get rid of the number Jekyll adds, I found part of the solution on this site. A little further research yielded the other part. So at the end I copied the file assets/main.scss from the minima style that I’m using at the momtent into my Jekyll project (into the directory assets) and added the following line to the end of it.

ol.bibliography li { list-style: none }

I don’t quite like the way the number of the references in the bibliography show up now, but I’m to lazy to figure out how to change it right now. I might do that sometime later (probably not).

2020-02-11:

Well, I actually changed it. So, first of all I removed the added line in assets/main.scss. Than I copied the file ieee.csl from ~/.rvm/gems/ruby-2.4.1/gems/csl-styles-1.0.1.9/vendor/styles/ieee.csl into the assets directory and renamed it to ieee_without_reference_numbers.csl. In that file I commented out the line that is responsible for adding the reference number. The line:

      <text variable="citation-number" prefix="[" suffix="]"/>

became:

      <!-- <text variable="citation-number" prefix="[" suffix="]"/> -->

The last touch was to change the following line in the scholar section of the \_config.yml file:

style: ./assets/ieee_without_reference_numbers

Change Log

2022-09-08:

  • I made some minor changes to the text (change some formatting, removed some typos, stuff like that).
  • Added the change to a line in ieee_without_reference_numbers.csl. Somehow I missed to explain what I did with the original file beside copying it.



Take care,
Andreas

References

  1. Jekyll, “Jekyll • Simple, blog-aware, static sites | Transform your plain text into static websites and blogs.” [Online]. Available at: https://jekyllrb.com/. [Accessed: 06-Dec-2021].
  2. S. Keil, “Jekyll-Scholar.” [Online]. Available at: https://github.com/inukshuk/jekyll-scholar. [Accessed: 06-Dec-2021].

Updated:

Leave a comment