Chapter 6 Make it yours

Now it is time to personalize your R Markdown document to make it a lesson that works for you and your learners.

6.1 Add code

# a code comment
sample(c("fun", "fancy"), 1)

You can insert new code chunks into your document in the RStudio IDE by putting your cursor in your doc where you want to plant your new chunk, then clicking on the button.

This adds the chunk delimiters ```{r} and ``` for you, and you place your code inside. Use # to add comments to your code.

6.2 Embrace Markdown

One of the not-very-secret weapons of the most skilled R Markdown users is knowing Markdown inside and out. If you haven’t done so already, take 10 minutes to do an interactive Markdown tutorial.

From within the RStudio IDE, you can also access a “Markdown Quick Reference” from the Help menu. This renders a cheatsheet-style document in your Help viewer pane, so you can try to jog your memory without leaving your project.

6.3 Add structure with headers

Headers are useful for organizing your document into sections, and with Markdown formatting you can have up to 6 types/sizes of headers. Use a # symbol before the label to create a new header.

Header 1

Header 2

Header 3

Header 4

Header 5
Header 6

The RStudio IDE has several built-in features made to improve quality of life for R Markdown users.

RStudio code navigator

Figure 6.1: RStudio code navigator

One feature is the drop-down code navigator in the bottom-left of your file editor as shown in Figure 6.1 (from the R for Data Science book).

As you can see, this uses your Markdown headers to allow you to navigate around your .Rmd file.

You can also use the RStudio outline pane, as shown in Figure 6.2 (from the RStudio blog).

RStudio outline pane

Figure 6.2: RStudio outline pane

6.4 Add narrative

Start writing! You can add words anywhere in your document below the YAML, just be sure you aren’t adding non-R-code inside any code chunks.

Let’s take a lightly-edited snippet from a Wikipedia about “The Great British Bake Off”. On the left, you can see the raw Markdown and on the right, the rendered version.

The Great British Bake Off

The Great British Bake Off (also called Bake Off or GBBO) is a British television baking competition.

In the first series, the location of the cast and crew moves from town to town each week, with a different baking theme each week:

  1. Cakes
  2. Biscuits
  3. Bread
  4. Puddings
  5. Pastry
  6. Tea Party (Final)

In each episode, the amateur bakers are given three challenges based on that week’s theme:

  • A signature bake,
  • a technical challenge,
  • and a show-stopper.


Vanilla Macaron, Michelle Naherny

6.5 Add space

Let your words and code chunks breathe! This is unfortunately a bit manual. But–if you don’t plan on doing any CSS, then we highly recommend doing the below:

  • Add white space in the body of your .Rmd file by including either a <br> or a \ on its own line with a blank line above and below it. At a minimum, we recommend doing before top-level section headers.

“Code needs a lot of whitespace. That’s how it breathes.”

Roger Peng