1.5 R Markdown vs. Markdown

If you are not familiar with R Markdown, please see Appendix A for a quick tutorial. When you create a new post, you have to decide whether you want to use R Markdown or plain Markdown, as you can see from Figure 1.2.

Table 1.2 summarizes the main differences between the three options, followed by detailed explanations below.

TABLE 1.2: Differences among the three document formats.
Feature .Rmd .Rmarkdown .md
Run R code yes yes no
Bibliography yes yes no
Task list maybe yes yes
MathJax yes maybe maybe
HTML widgets yes yes no

  1. You cannot execute any R code in a plain Markdown document, whereas in an R Markdown document, you can embed R code chunks (```{r}). However, you can still embed R code in plain Markdown using the syntax for fenced code blocks ```r (note there are no curly braces {}). Such code blocks will not be executed and may be suitable for pure demonstration purposes. Below is an example of an R code chunk in R Markdown:

    ```{r cool-plot, fig.cap='A cool plot.'}
plot(cars, pch = 20)  # not really cool
```

    And here is an example of an R code block in plain Markdown:

    ```r
1 + 1  # not executed
```

  2. A plain Markdown post is rendered to HTML through Blackfriday (a package written in the Go language and adopted by Hugo). An R Markdown document is compiled through the packages rmarkdown, bookdown, and Pandoc, which means you can use most features of Pandoc’s Markdown and bookdown’s Markdown extensions in blogdown. If you use R Markdown (Allaire et al. 2020) with blogdown, we recommend that you read the documentation of Pandoc and bookdown at least once to know all the possible features. We will not repeat the details in this book, but list the features briefly below, which are also demonstrated on the example website https://blogdown-demo.rbind.io.

    • Inline formatting: _italic_ / **bold** text and `inline code`.

    • Inline elements: subscripts (e.g., H~2~0) and superscripts (e.g., R^2^); links ([text](url)) and images ![title](url); footnotes text^[footnote].

    • Block-level elements: paragraphs; numbered and unnumbered section headers; ordered and unordered lists; block quotations; fenced code blocks; tables; horizontal rules.

    • Math expressions and equations.

    • Theorems and proofs.

    • R code blocks that can be used to produce text output (including tables) and graphics. Note that equations, theorems, tables, and figures can be numbered and cross-referenced.

    • Citations and bibliography.

    • HTML widgets, and Shiny apps embedded via <iframe>.

There are many differences in syntax between Blackfriday’s Markdown and Pandoc’s Markdown. For example, you can write a task list with Blackfriday but you could not with Pandoc until recently:16

- [x] Write an R package.
- [ ] Write a book.
- [ ] ...
- [ ] Profit!

Similarly, Blackfriday does not support LaTeX math and Pandoc does. We have added the MathJax support to the default theme (hugo-lithium) in blogdown to render LaTeX math on HTML pages, but there is a caveat for plain Markdown posts: you have to include inline math expressions in a pair of backticks `$math$`, e.g., `$S_n = \sum_{i=1}^n X_i$`. Similarly, math expressions of the display style have to be written in `$$math$$`. For R Markdown posts, you can use $math$ for inline math expressions, and $$math$$ for display-style expressions.17

If you find it is a pain to have to remember the differences between R Markdown and Markdown, a conservative choice is to always use R Markdown, even if your document does not contain any R code chunks. Pandoc’s Markdown is much richer than Blackfriday, and there are only a small number of features unavailable in Pandoc but present in Blackfriday. The main disadvantages of using R Markdown are:

  1. You may sacrifice some speed in rendering the website, but this may not be noticeable due to a caching mechanism in blogdown (more on this in Section D.3). Hugo is very fast when processing plain Markdown files, and typically it should take less than one second to render a few hundred Markdown files.

  2. You will have some intermediate HTML files in the source directory of your website, because blogdown has to call rmarkdown to pre-render *.Rmd files into *.html. You will also have intermediate folders for figures (*_files/) and cache (*_cache/) if you have plot output in R code chunks or have enabled knitr’s caching. Unless you care a lot about the “cleanness” of the source repository of your website (especially when you use a version control tool like GIT), these intermediate files should not matter.

In this book, we usually mean .Rmd files when we say “R Markdown documents,” which are compiled to .html by default. However, there is another type of R Markdown document with the filename extension .Rmarkdown. Such R Markdown documents are compiled to Markdown documents with the extension .markdown, which will be processed by Hugo instead of Pandoc. There are two major limitations of using .Rmarkdown compared to .Rmd:

  • You cannot use Markdown features only supported by Pandoc, such as citations. Math expressions only work if you have installed the xaringan package (Xie 2020d) and applied the JavaScript solution mentioned in Section B.3.

  • HTML widgets are not supported.

The main advantage of using .Rmarkdown is that the output files are cleaner because they are Markdown files. It can be easier for you to read the output of your posts without looking at the actual web pages rendered. This can be particularly helpful when reviewing GitHub pull requests. Note that numbered tables, figures, equations, and theorems are also supported. You cannot directly use Markdown syntax in table or figure captions, but you can use text references as a workaround (see bookdown’s documentation).

For any R Markdown documents (not specific to blogdown), you have to specify an output format. There are many possible output formats in the rmarkdown package (such as html_document and pdf_document) and other extension packages (such as tufte::tufte_html and bookdown::gitbook). Of course, the output format for websites should be HTML. We have provided an output format function blogdown::html_page in blogdown, and all R Markdown files are rendered using this format. It is based on the output format bookdown::html_document2, which means it has inherited a lot of features from bookdown in addition to features in Pandoc. For example, you can number and cross-reference math equations, figures, tables, and theorems, etc. See Chapter 2 of the bookdown book (Xie 2016) for more details on the syntax.

Note that the output format bookdown::html_document2 in turn inherits from rmarkdown::html_document, so you need to see the help page ?rmarkdown::html_document for all possible options for the format blogdown::html_page. If you want to change the default values of the options of this output format, you can add an output field to your YAML metadata. For example, we can add a table of contents to a page, set the figure width to be 6 inches, and use the svg device for plots by setting these options in YAML:

---
title: "My Awesome Post"
author: "John Doe"
date: "2017-02-14"
output:
  blogdown::html_page:
    toc: true
    fig_width: 6
    dev: "svg"
---

To set options for blogdown::html_page() globally (i.e., apply certain options to all Rmd files), you can create a _output.yml file under the root directory of your website. This YAML file should contain the output format directly (do not put the output format under the output option), e.g.,

blogdown::html_page:
  toc: true
  fig_width: 6
  dev: "svg"

At the moment, not all features of rmarkdown::html_document are supported in blogdown, such as df_print, code_folding, code_download, and so on.

If your code chunk has graphics output, we recommend that you avoid special characters like spaces in the chunk label. Ideally, you should only use alphanumeric characters and dashes, e.g., ```{r, my-label} instead of ```{r, my label}.

It is not recommended to change the knitr chunk options fig.path or cache.path in R Markdown. The default values of these options work best with blogdown. Please read Section D.5 to know the technical reasons if you prefer.

If you are working on an R Markdown post, but do not want blogdown to compile it, you can temporarily change its filename extension from .Rmd to another unknown extension such as .Rmkd.

References

Allaire, JJ, Yihui Xie, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, Hadley Wickham, Joe Cheng, Winston Chang, and Richard Iannone. 2020. Rmarkdown: Dynamic Documents for R. https://github.com/rstudio/rmarkdown.

Xie, Yihui. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/bookdown.

Xie, Yihui. 2020d. Xaringan: Presentation Ninja. https://github.com/yihui/xaringan.

  1. Support for task lists was added to Pandoc with version 2.6, released on January 2019.↩︎

  2. The reason that we need the backticks for plain Markdown documents is that we have to prevent the LaTeX code from being interpreted as Markdown by Blackfriday. Backticks will make sure the inner content is not translated as Markdown to HTML, e.g., `$$x *y* z$$` will be converted to <code>$$x *y* z$$</code>. Without the backticks, it will be converted to $$x <em>y</em> z$$, which is not a valid LaTeX math expression for MathJax. Similar issues can arise when you have other special characters like underscores in your math expressions.↩︎