4 Rendering Documents

When you render a document, the code is run and the code and results are included in a document written in Markdown. This is then further processed into your final output format.

There are a number of different ways you can render your documents. To render a single document using RStudio you can

  • open the document and click on the “Knit” button at the top of the Rstudio editor pane.
  • open the document and use the <control>-<shift>-<K> key combination
  • use a rendering function in an R script or in the R Console to process an already-saved file.

4.1 RStudio GUI versus R Functions

There is a crucial distinction to be made between rendering a document interactively using the RStudio graphical user interface (GUI), and using R functions in a script or in the Console.

  • To render documents interactively you would generally include the library(Statamarkdown) in an initial code chunk in your document.

  • To render documents via scripted functions, you generally load the Statamarkdown library prior to rendering.

It is OK to have a library(Statamarkdown) statement both prior to the render function and within the document.

4.2 Rendering a Single Document

When rendering a document interactively the library(Statamarkdown) statement must be inside your document

However, if you are using R functions to render your documents then you will want to load Statamarkdown prior to running your script. If the library is loaded only within each document, the first document will be rendered correctly but subsequent documents will lose their Statamarkdown settings and produce errors. The convenient thing to do in this case is to load the library prior to running the rendering functions.

4.3 Rendering Multiple Documents

You can, of course, open multiple documents and render them one at a time using the GUI.

To render more than one document, load the Statamarkdown package prior to rendering documents that use it.

library(Statamarkdown)

If you are rendering just a single document, loading the Statamarkdown library can occur within the document. If you ever render the document by using the “knit” button in RStudio, or the <shift>-<control>-<k> key combination the library(Statamardown) statement must be within the document. And if you have loaded the Statamarkdown library prior to using the render function, there is no harm in including library(Statamarkdown) within your document, it will just be ignored.

However, if your library(Statamarkdown) statements appear only within your documents, after the first document the engine.path and other chunk options that Statamarkdown uses will be lost, and the document will not be rendered.

You might also load the knitr and rmarkdown packages, but this is not necessary.

# optional
library(knitr)
library(rmarkdown)

As an example, render the same document twice.

library(Statamarkdown)
rmarkdown::render("Statamarkdown_Render_Test.Rmd")
rmarkdown::render("Statamarkdown_Render_Test.Rmd", output_file = "Statamarkdown_Render_Test2")

These functions from the knitr package produce an HTML fragment, suitable for including within another HTML document.

knitr::knit2pandoc("Knitr_Render_Test.Rmd")
knitr::pandoc(knitr::knit("Knitr_Render_Test.Rmd"))

Quarto, on the other hand, behaves the same whether or not you have already loaded Statamarkdown, and whether or not you have already rendered another document using Statamarkdown.

quarto::quarto_render("Knitr_Render_Test.Rmd")
quarto::quarto_render("Knitr_Render_Test.Rmd", output_file = "Knitr_Render_Test2")

This page was written using:

  • Statamarkdown version 0.9.2
  • knitr version 1.45