How to use R Markdown (part two): for learning R!

[This article was first published on R on R (for ecology), and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Welcome to part two of my blog series on R Markdown. In the first part, I went over how to create a basic R Markdown document and how to use R Markdown syntax. In this post, I’m going to talk about how you can use R Markdown to learn R.

Left side shows the R Markdown logo with an arrow to the right pointing to the R logo. Behind this there is a faded image of someone studying from a book that covers their face.

So why is R Markdown good for learning R? As you saw in the first post, R Markdown is a method for typing normal and formatted text alongside your R code and its outputs. This is perfect for documenting your analyses by taking notes on specific chunks of code and writing down what worked or didn’t work. This same process is perfect for creating tutorials (like the one here!) and keeping track of what you learn. Eventually, the end goal is to have a series of R Markdown documents that cover all the topics and code that you learn, which include both the code and notes explaining what everything does. These documents then also serve as a guide that you can refer back to for troubleshooting or jogging your memory.

In other words, using R Markdown to learn R allows you to:

  • Have a project-based learning experience

  • Fully document your learning

  • Create a reference that you can look back on in the future if you get stuck or can’t remember something

  • Learn by teaching because you’re explaining things in your own words and taking notes

  • Create a teaching resource for yourself that you can then use to help others as well

You can also follow along with this post as a video if you click on the image below. Start the video at 35:35 to cover the material in this post.

Image of Youtube play button on top of a tutorial for R Markdown created by R for Ecology

Getting set up

To use R Markdown, you’ll need to have R and RStudio already installed. If you need help with downloading R and RStudio, you can check out my blog post and lessons one, two, and three of my online course.

You’ll also have to install two packages: rmarkdown and knitr. To do that you can run install.packages("rmarkdown") and install.packages("knitr"). You’ll only need to do this once for your computer (at least until the next time you update R).

If you are completely new to R and R Markdown, then I strongly suggest you start with my previous blog post on how to use R Markdown (after going through the three lessons linked above). It goes through all the most important tools in R Markdown.

With the basic software and packages installed, the first thing is to create a new RStudio project where you’ll be working on your R Markdown documents. RStudio projects are incredibly helpful for file organization and managing working directories, and they remove the need to use functions like setwd() and getwd(). You can read more about RStudio projects in our post on the subject here.

To learn more about RStudio Projects and why you should always use them, check out these three other great posts from other blogs:

Go to “File” and click on “New Project…”.

Image showing cursor hovering over File and New Project

This will open a new window, where you’ll click on “New Directory” and “New Project”. That should take you to the next window, where you can give your project a name, like “Learning R” and then can choose somewhere to save it. Then hit “Create Project”, and you’ll have a new RStudio project.

Image of Create New Project window, where you can give your project a name and save it somewhere

Now that you’ve created your new project, anytime you want to work on it, all you have to do is just open the ‘.Rproj’ file, and RStudio will open up with the scripts you were working on (R Markdown documents in this case).

Image showing cursor hovering over new .Rproj file

With this R project open, go to “File” » “New File” and click on “R Markdown…”

Image showing cursor hovering over File and R Markdown

Give your R Markdown document a title and hit OK. I titled my document “The basics”.

Image showing new R Markdown document titled “The basics”

Organizing your documents

One method is to create new R Markdown documents for every topic you cover. You might start off with one document that covers the basics, then the next one might cover how to upload data, and then you’ll have another one for data visualization, etc.

If you still want to create one large R Markdown document, or if you have sub-topics within your larger topics, you can add a table of contents to your document. Do this by going to the gear button at the top of the document and clicking on “Output Options”.

Image showing cursor hovering over the gear button and output options

From there, a window will open up and you can check the box “Include table of contents”.

Image with the option “include table of contents” selected and circled

After that, you’ll notice that the text “toc: yes” appears at the top of your R Markdown document. When you knit your document, any headers you’ve added will appear in the table of contents at the top (like my header, “The basics”). The table of contents is clickable, so it will take you to wherever that section is in your document.

Image showing a side by side comparison of the R Markdown code with the knitted R Markdown document. The knitted document has a table of contents at the top with a hyperlink that takes you to the section called “The basics”

You can also number the table of contents and the section headings by checking that option in the “Output Options” window.

Image showing the “Number section headings” option selected and circled

Numbering the sections can help your document become more clearly organized. If you add subsections, the document will take that into account when numbering. For example, my section 1 is called “The basics”. I made two subsections within “The basics”, called “Defining variables” and “Vectors”. “Defining variables” is given the number 1.1 and “Vectors” is given the number 1.2 because they’re nested under section 1. You can also see that in the table of contents, the subsections are tabbed in under their umbrella section to show that they’re nested.

Image of table of contents with sections and subsections. The umbrella section is called “The basics”, and there are two subsections, called “Defining variables” and “Vectors”

Dealing with errors

I want to show you one more thing that I like to do when using R Markdown for learning. Sometimes we get errors that show up, and we aren’t sure how to resolve them. For example, in the code below, I get an error that says my variable can’t be found (this is because I haven’t created a variable called “my_number” yet).

Image of code saying “is my number greater than 5?” and an error message that says “Error: object ‘my_number’ not found”.

When you have an error in your code, R Markdown won’t let you knit the document unless you’ve resolved the error. One thing you could do is to delete the problematic code, but then you might make the same mistake in the future. What you can do instead is copy and paste the error message and insert it in your code chunk as a comment. Then also comment out the code that caused the error, allowing you to knit the document. Then your code chunk might look something like this.

Code that says “my code made this error and I can’t figure it out yet”, with the code and error message included as comments Now, if you share your document with someone, they can see the error and help you resolve it. Or maybe you’ll come back to the document in the future, see your note, and figure it out on your own after leaving the code alone for a bit.

Learning workflow

To summarize, here is a workflow that you can follow for learning R with R Markdown:

  1. Start by creating the empty R project and your first R Markdown document (making sure to clear out the example contents of the new R Markdown document). Also make sure to add in a table of contents if you plan on keeping it all in one longer document.

  2. Then, as you follow through any tutorials (or online courses! 😄), start new section headings (using ‘#’s) and begin explaining the steps you take to complete the tutorial or lesson.

  3. After each set of text or description, add in the associated R code chunk.

  4. Knit your document often to see the changes you are making as a stand-alone document and to make sure there are no errors in your code.

  5. Follow the steps above for dealing with errors as they come up.

  6. Finally, refer back to your knitted HTML document as often as you need, or even print it out as a physical reference if that helps.

All of the tips that I included in this blog post are intended to help you document your learning process. Taking notes and analyzing your own code can help ensure that everything you’re learning is sticking in your head.

And that’s it for my R Markdown tutorial series! I hope you enjoyed these posts. Remember to keep adding to your documents as you learn—it will help you grasp new topics and can even turn the R learning curve into a fun project!

Have any cool R Markdown documents you’ve created? Share links in the comments below! 👇



If you liked this post and want to learn more, then check out my online course on the complete basics of R for ecology. The course is *perfectly* suited for creating your own R Markdown document as you follow along!

Also be sure to check out R-bloggers for other great tutorials on learning R

To leave a comment for the author, please follow the link and comment on their blog: R on R (for ecology).

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)