What is the relationship between the functionality of R Markdown, Knitr, Pandoc, and Bookdown?
Specifically what is the 'division of labour' between these packages in converting markup documents with embedded R code (e.g.
Pandoc is a document converter. It can convert from a number of different markup formats to many other formats, such as
Pandoc is a command line tool with no GUI. It is an independent piece of software, separate from R. However, it comes bundled with R Studio because
rmarkdown relies on it for document conversion.
Pandoc not only converts documents, but it also adds functionality on top of the base markdown language to enable it to support more complex outputs.
R Markdown is based on markdown:
Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats. A markdown file is a plain text file that is typically given the extension
Like other markup languages like HTML and Latex, it is completely independent from R.
There is no clearly defined Markdown standard. This has led to fragmentation as different vendors write their own variants of the language to correct flaws or add missing features.
R Markdown is an extension of the markdown syntax. R Markdown files are plain text files that typically have the file extension
.Rmd. They are written using an extension of markdown syntax that enables R code to be embedded in them in a way which can later be executed.
Because they are expected to be processed by the
rmarkdown package, it is possible to use Pandoc markdown syntax as part of a R markdown file. This is an extension to the original markdown syntax that provides additional functionality like raw HTML/Latex and tables.
The R package
rmarkdown is a library which proceses and converts
.Rmd files into a number of different formats.
The core function is
rmarkdown::render which stands on the shoulders of pandoc. This function 'renders the input file to the specified output format using pandoc. If the input requires knitting then
knitr::knit is called prior to pandoc.
The RMarkdown package's aim is simply to provide reasonably good defaults and an R-friendly interface to customize Pandoc options..
The YAML metadata seen at the top of RMarkdown files is specificially to pass options to
rmarkdown::render, to guide the build process.
Note that RMarkdown only deals with markdown syntax. If you want to convert a
.Rhtml or a
.Rnw file, you should use the convenience functions built into
Knitr, such as
Knitr takes a plain text document with embedded code, executes the code and 'knits' the results back into the document.
For for example, it converts
.Rmd) file into a standard markdown file (
.Rnw(Sweave) file into to
.Rhtmlfile into to html.
The core function is
knitr::knit and by default this will look at the input document and try and guess what type it is - Rnw, Rmd etc.
This core function performs three roles:
- A source parser, which looks at the input document and detects which parts are code that the user wants to be evaluated.
- A code evaluator, which evaluates this code
- An output renderer, which writes the results of evaluation back to the document in a format which is interpretable by the raw output type. For instance, if the input file is an
.Rmd, the output render marks up the output of code evaluation in
Knitr does not convert between document formats - such as converting a
.md into a
.html. It does, however, provide some convenience functions to help you use other libraries to do this. If you are using the
rmarkdown package, you should ignore this functionality because it has been superceded by
An example is
knitr:knit2pdf which will: 'Knit the input Rnw or Rrst document, and compile to PDF using texi2pdf or rst2pdf'.
A potential source of confusion is
knitr::knit2html, which "is a convenience function to knit the input markdown source and call
markdown::markdownToHTML to convert the result to HTML." This is now legacy functionality because the
markdown package has been superceded by the
rmarkdown package. See this note.
The bookdown package is built on top of R Markdown, and inherits the simplicity of the Markdown syntax , as well as the possibility of multiple types of output formats (PDF/HTML/Word/…).
It offers features like multi-page HTML output, numbering and cross-referencing figures/tables/sections/equations, inserting parts/appendices, and imported the GitBook style (https://www.gitbook.com) to create elegant and appealing HTML book pages.