Relationship Between R Markdown, Knitr, Pandoc, and Bookdown

Relationship between R Markdown, Knitr, Pandoc, and Bookdown

Pandoc

Pandoc is a document converter. It can convert from a number of different markup formats to many other formats, such as .doc, .pdf etc.

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

R Markdown is based on markdown:

Markdown (markup language)

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 .md.

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.

Markdown (R package)

markdown is an R package which converts .Rmd files into HTML. It is the predecessor of rmarkdown, which offers much more functionality. It is no longer recommended for use.

R Markdown (markup language)

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.

R Markdown (package)

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::knit2html and knitr:knit2pdf

Knitr

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

• An R Markdown (.Rmd) file into a standard markdown file (.md)
• An .Rnw (Sweave) file into to .tex format.
• An .Rhtml file 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 .md format.

Converting between document formats

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 rmarkdown::render.

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.

Bookdown

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.

New Pandoc distrib = loose cross-references (RMarkdown - knitr - Bookdown - thesisdown - R)

It seems that install or reinstall tinytext is the key for solving this problem. If not, just go further with packages update (e.g., bookdown, thesisdown). Sometimes, you need to reinstall Rstudio (solve this kind of problem, or some package update issues).

knitr::include_graphics() doesn't render figure with `bookdown`

I had the same issue and it seems you will need to pass the absolute path. See this .

Instead of using here maybe try using normalizePath in include_graphics.

So omit your call here(), which may not be propagating across chunks (I don't know, because I can't see your chunks), and do:

knitr::include_graphics(normalizePath("output/figures/chapter1/top100/top100_2000.jpeg"))

In Windows I add winslash = "/":

knitr::include_graphics(normalizePath("output/figures/chapter1/top100/top100_2000.jpeg", winslash = "/"))

Customising Colour / Boldness in Markdown with RMarkdown / Bookdown

Per your request, you can change the styles in HTML outputted R Markdown scripts by adding styles. There are a few different ways you can add them. Typically, I just place this content in between chunks.

<style>
blockquote {
  font-color: black; 
  opacity: 1;}
</style>

You can attach an external style document or use a CSS chunk. I just find this easier for most projects.

You can read more about this here.

Remove colon in figure caption using pandoc and bookdown in R Markdown

Looks like there was a change in rmarkdown which adds a colon by default. Also the reason why the answer in the linked post does not work anymore. For more on this and a solution see https://community.rstudio.com/t/how-to-change-the-figure-table-caption-style-in-bookdown/110397.

Besides the solution offered there you could achieve your desired result by replacing the colon by a dot. Adapting the lua filter provided by https://stackoverflow.com/a/59301855/12993861 this could done like so:

function Image (img)
  img.caption[1] = pandoc.Strong(img.caption[1])
  img.caption[3] = pandoc.Strong(pandoc.Str(string.gsub(img.caption[3].text, ":", ".")))
  return img
end

---

Related Topics