1.1 Use a Pandoc version not bundled with the RStudio IDE

The RStudio IDE has bundled a version of Pandoc, so you do not need to install Pandoc by yourself if you use the RStudio IDE. However, for some advanced usage, the bundled version may differ from the exact version you want. You can choose to install a separate copy of Pandoc by yourself. Please remember that the bundled version may be more thoroughly tested with R Markdown, because most RStudio users may just use the bundled version. If you want to go with a different version (especially a higher version), you might run into problems that other R Markdown users or developers have yet to discover.

Some configurations are required if you have installed a specific Pandoc version by yourself.

First, before running rmarkdown::render(), you may inform the rmarkdown package by calling the function rmarkdown::find_pandoc() in the same R session, e.g.,

# to find a specific version (e.g., if lower version
# on PATH)
rmarkdown::find_pandoc(version = "2.9.1")

# to find Pandoc under a specific directory (e.g., if
# a specific version cannot be in PATH)
rmarkdown::find_pandoc(dir = "~/Downloads/Pandoc")

# ignore the previously found Pandoc and search again
# (i.e., opt out of the caching mechanism).
rmarkdown::find_pandoc(cache = FALSE)

As you can see in the above code chunk, several ways exist to find a version of Pandoc. By default, rmarkdown::find_pandoc() tries to find your system’s highest version of Pandoc. Once found, the version information is cached, and you can invalidate the cache with cache = FALSE. Please see the help page ?rmarkdown::find_pandoc for the potential directories where the pandoc executable may be found.

This function needs to be called outside of the Rmd document, as rmarkdown may use the Pandoc version information before knitting with code cells execution happens.

If you want an Rmd document to be compiled by a specific version of Pandoc installed on your computer, the pandoc package (Dervieux 2023) will help. This package is designed to help test R code with different Pandoc versions. It allows installing and managing several Pandoc binary versions on the system and easily switching between versions. The function pandoc::with_pandoc_version() can help to render a document with a specific version of Pandoc, e.g., the following will render the document with Pandoc 2.9.1:

pandoc::with_pandoc_version(
  version = '2.9.1',
  rmarkdown::render('input.Rmd')
)

The pandoc package works by default with its Pandoc binaries installation. See ?pandoc::pandoc_install() for installation instructions of 2.9.1 in the example and, more generally, the Get Started article.

For use with the Knit button in RStudio (See Section 17.5 about Knit button customization.), you can also customize the behavior like this:

knit: (function(input, ...) { pandoc::with_pandoc_version("2.9.1", rmarkdown::render(input)) })

pandoc::with_pandoc_version() is a wrapper for rmarkdown::find_pandoc(), so you could also get inspiration from it to use your own version. See ?pandoc::with_pandoc_version() for more details.

References

Dervieux, Christophe. 2023. Pandoc: Manage and Run Universal Converter Pandoc from r. https://github.com/cderv/pandoc.