R Markdown is a document authoring format used by many data scientists. In this lab, you will explore some of the advanced formatting features of R Markdown to achieve a professional look.

Goal: by the end of this lab, you will be able to format an article in R Markdown using many advanced features.

R Markdown HTML

An R Markdown document can be rendered into many different formats. Since the piece we are writing is for the Web, we will render our document into HTML. In addition to the knitr chunk options that control how your R code gets rendered, R Markdown provides a number of features that can make your HTML document more expressive.

These features can be unlocked by setting parameters in the YAML header. YAML is an abbreviation for “Yet Another Markup Language”, and it is just a syntax for specifying options (like you might in a configuration file).

The following features are described in the R Markdown HTML documentation. Please consult that for instructions on how to use these features.

Figure options

For the web, it’s a good idea to make your figures as wide as the text around which they are inserted. Please also use captions to contextualize the graphic! [By “figures”, here we mean data graphics—not images.]

  1. Start a new R Markdown document (from the File menu) and render it. Experiment with the fig_width YAML setting and note how it changes the figure widths.

Side-by-side images

You can have two plots go side-by-side by using the fig.show and out.width chunk options. Set fig.show to "hold" and set out.width to "50%". This will result in each plot only occupying half of the space allotted to the line.

library(tidyverse)
plot <- ggplot(mtcars, aes(x = cyl, y = mpg)) + 
  geom_point()

# left image
plot
# right image
plot + 
  geom_line()

Data frame printing

If you have to display a large data table, it would be nice to allow your readers the chance to page and scroll through it. Use the Paged Printing option by setting df_print: paged in YAML.

---
title: "My document"
output:
  html_document:
    df_print: paged
---
  1. Turn on paged data frame printing and then print a data frame.

Code folding

Please use code folding, with the default set to hide.

  1. Turn on code_folding for your Markdown document and set the default to hide.

Themes

If you want to experiment with different themes, choose one from this Bootswatch theme gallery.

  1. Try using a different theme, and note how it changes the output of your document.

Inline R code

In addition to having chunks, you can include R code inline. This is very convenient when you have a sentence that contains a value that you need to compute. For example, you can write the current date like this:

The date is `r format(Sys.Date(), "%B %e, %Y")`

and it will render like this: The date is February 4, 2021.

Here is another example: the average of the first 100 uniform random numbers that I drew was 0.518509.

  1. This document was rendered at February 4, 2021 at 15:56:32. Write a similar sentence that will always give the correct time.
# Sample solution
This document was rendered at `r format(Sys.time(), "%B %e, %Y at %H:%M:%S"))`

Pandoc Markdown

Recall that R Markdown is an extension to the more general document authoring syntax called Markdown. A popular and versatile software for rendering Markdown documents is Pandoc. Thus, R Markdown documents can leverage many (all?) of the features available through Pandoc Markdown. These features have nothing to do with R coding, but provide a rich (and growing) authoring experience.

I now write all of my letters, class notes, slides, websites, articles, and even my CV in Markdown (or LaTeX). Word processing software is dead to me!

Please see the extensive Pandoc Markdown documentation. Use only what you need!

In particular, check out:

  • Lists
  • Links
  • Images
  • Footnotes
  • Citations

Wonder Woman

In this lab, your overall goal is to mimic the appearance of “Three Reasons ‘Wonder Woman’ Has Already Made History”, an article published at FiveThirtyEight.com. Please consult the R Markdown HTML documentation here:

https://rmarkdown.rstudio.com/html_document_format.html

  1. Copy the text of this article and paste it into a new R Markdown document. Add the paragraph breaks manually if they are not already there.

  2. Add the image of Wonder Woman.

  3. Add some links to the text, where appropriate.

  4. Add a footnote.

  5. Add the data graphic as an embedded image.

  6. Use the Paged data frame Printing option and display a data table. [It doesn’t matter what the content of the data table is.]

  7. Change the Bootstrap theme.

  8. Insert an inline bit of R code that will automatically display the current date when the page is rendered.

Your learning

Please respond to the following prompt on Slack in the #mod-programming channel.

Prompt: What questions do you still have about the HTML features of R Markdown?