Jekyll-scholar is a plugin that can be used to add Bibtex references to Markdown tutorials.
Adding references to a tutorial with Jekyll-scholar
To add references add the bibtex library to the repository root. Add an empty yaml header to the bibtex file so Jekyll-scholar will know to parse the file. Do this by adding these two lines to the start of the file,
---
---
To print the references in your tutorial, assuming your tutorial is called My-Awesome-Tutorial and your references are saved in a file called master_refs.bib, add the line,
{% bibliography --cited --file My-Awesome-Tutorial/master_refs.bib %}
to README.md at the location you want to print the bibliography. This will print all cited references. To cite a reference simply add,
{% cite AwesomeBook --file My-Awesome-Tutorial/master_refs.bib %}
This will add a citation to a reference saved as “AwesomeBook” in the file master_refs.bib. Note that you have to always enter the name of the bibtex file and enter the path relative to the parent directory of your GitHub repository.
Common issues with Jekyll-scholar
- For the moment Jekyll-scholar cannot parse items enclosed between double braces ({
{ and }}), but interprets it as a liquid tag. - Jekyll-scholar can only parse your bibliography if it is encoded in UTF-8. This can easily be done in most text proper text editors (e.g. Sublime).