Let’s summarize what we have seen so far and preview what is to come.
Rendering R Markdown documents with rmarkdown consists of converting
.md with knitr, and then
.md to our desired output with Pandoc (typically).
.md step handles the execution and “translation” of all code within our report, so most changes to content involve editing the
.Rmd with code for knitr to translate. Tools that we have control over these steps include knitr chunk options and hooks.
.md is a plain text file with no formatting. This is where Pandoc comes in to convert to the final output format such as HTML, PDF, or Word. Along the way, we add structure and style. A wide range of tools to help us in this process include style sheets (CSS), raw LaTeX or HTML code, Pandoc templates, and Lua filters. By understanding the nested structure of an R Markdown document, and by thoughtfully using identifiers and classes, we can apply some of these tools selectively to targeted parts of our output.
Finally, our YAML metadata may help us toggle any of these steps. Changing parameters can change how our code runs, changing metadata alters the text content, and changing output options provides the
render() function with a different set of instructions.
Of course, these are all rough heuristics and should not be taken as absolute facts. Ultimately, there is not a completely clear division of labor. Throughout this book, you will see that there are often multiple valid paths to achieving many of the outcomes described in this book, and these may enter different stages of the pipeline. For example, for the simple task of inserting an image in your document, you may either use the R code
knitr::include_graphics(), which would execute in the
.md stage, or directly use Markdown syntax (
!()). This may seem confusing, and sometimes different approaches will have different advantages. However, do not be concerned—if anything, this often means there are many valid ways to solve your problem, and you can follow whichever approach makes the most sense to you.
And that’s that! In the rest of the book, you can now color in this rough sketch with many more concrete examples of ways to modify all of the components that we have discussed to get the most value out of R Markdown.