Enabling rmarkdown/pandoc-citeproc Citations in Jekyll Blog via Server

Introduction to rmarkdown and Pandoc-Citeproc

This article aims to provide a step-by-step guide on enabling citations in R Markdown documents using the rmarkdown and pandoc-citeproc packages in a Jekyll blog setup. We’ll explore how to modify the servr::jekyll() function to utilize these features.

Background: Jekyll, rmarkdown, and knitr

For those unfamiliar with the tools involved:

Jekyll is a static site generator that allows users to create websites using plain text files.
R Markdown is an authoring format that combines R code with Markdown formatting for creating documents.
knitr is a package that allows you to embed R code in Markdown documents and compile them into HTML.

The Problem: rmarkdown-citations not Working

When working with rmarkdown-Jekyll blogs, users often encounter issues with citations. Specifically, the pandoc-citeproc feature, which enables citation management using the citations-bib package, does not work as expected.

The provided Stack Overflow question illustrates this issue, where the author attempts to use bibliography: ../bibliography.bib in their Jekyll file but experiences unexpected results. The problem arises from the fact that the servr::jekyll() function runs files through knitr, which does not handle citations.

Solution: Using rmdv2()

To resolve this issue, we can leverage the rmdv2() function instead of jekyll(). This difference in functionality lies in how they compile R Markdown documents:

knit2html(): used by rmdv1(), compiles R Markdown using the markdown package (R Markdown v1).
render(): used by rmdv2(), compiles R Markdown using the rmarkdown package (R Markdown v2), which enables features like citation management.

Enabling rmarkdown/pandoc-citeproc Citations

To enable pandoc-citeproc citations, we need to use the rmdv2() function and specify the bibliography file in our Jekyll setup:

---
bibliography: ../bibliography.bib
---

This will tell rmdv2() to look for the specified bibliography file when compiling R Markdown documents.

Conclusion

In this article, we explored how to enable citations in a Jekyll blog using the rmarkdown and pandoc-citeproc packages. By understanding the differences between knit2html() and render(), as well as utilizing the rmdv2() function, users can successfully manage citations in their R Markdown documents.

Example Code: Using rmdv2()

To demonstrate this solution, let’s create a basic Jekyll file with an R Markdown document that includes citations:

_layouts/_default.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
  {{ content }}
</body>
</html>

_includes/header.html

<header>
  <title>{{ site.title }}</title>
</header>

_site/config.yml

---
title: Example Blog
author: Your Name
baseurl: /
show_downloads: false
theme: "jekyll-theme-minimal"
---

2014-09-28-jekyll-with-knitr.Rmd

## Citations

This work is built on top of Yihui's [fantastic boilerplate](https://yihui.name/knitr/) for using `knitr`.[@Yihui-2015]

See the references at the very bottom.

[@Yihui-2015]
Yihui Xie. 2016. R Markdown: The Ultimate Guide (2nd ed.). CRC Press.

_site/data/bibliography.bib

@book{Xie2016,
  title = {R Markdown: The Ultimate Guide (2nd ed.)},
  author = {Yihui Xie},
  year = {2016},
  publisher = {CRC Press}
}

@end{bib}

By using the rmdv2() function and specifying the bibliography file, we can successfully compile R Markdown documents with citations.

Next Steps

Experiment with different R Markdown features: Once you’ve enabled pandoc-citeproc citations, explore other features like tables of contents, figures, and more.
Customize your Jekyll theme: Tailor the look and feel of your blog by modifying the theme configuration in _config.yml.
Integrate with other tools: Consider integrating your R Markdown documents with other tools like GitHub, GitLab, or Bitbucket to enable version control and collaboration.

Last modified on 2024-04-27