Skip to main content
HomeTutorialsR Programming

R Markdown Tutorial for Beginners

Learn what R Markdown is, what it's used for, how to install it, what capacities it provides for working with code, text, and plots, what syntax it uses, what output formats it supports, and how to render and publish R Markdown documents.
Dec 2023  · 12 min read

This article will explore an essential and helpful data science package that every R user needs to know—R Markdown. We'll learn what R Markdown is, what benefits it offers, what it's used for, how to install it, what capacities it provides for working with code, narrative, and data plots, what syntax it uses, the output formats for R Markdown documents, and how to render such documents and share them with our collaborators.

Since R Markdown is particularly adapted for the RStudio integrated development environment (IDE), we're going to use this IDE throughout this article. The RStudio Tutorial provides the necessary guidance on how to install RStudio and begin using it.

Let's dive in!

What is R Markdown?

R Markdown is a free and open-source R package that provides a workspace for creating data science projects. The main advantage of R Markdown is that it allows you to combine code, text, and data visualizations in a single polished, shareable, fully reproducible document that can be rendered in a wide variety of output formats, both static and interactive.

Some of its popular output formats are HTML, PDF, Microsoft Word, presentations, applications, websites, dashboards, reports, templates, articles, books, etc.

In addition, R Markdown allows easy version control tracking and supports many programming languages besides R, including Python and SQL.

If you want to dig deeper into how to author dynamic reports with R Markdown, the course Reporting with R Markdown is the right place to start.

Installing R Markdown

When using R Markdown outside of RStudio, we install it in the same way as any other R package from the Comprehensive R Archive Network (CRAN) repository:

install.packages("rmarkdown")

After installation, we need to load the package in the working R environment:

library(rmarkdown)

Instead, when working with R Markdown within RStudio—which is what we're going to do throughout this tutorial—we don't need to explicitly install and load the rmarkdown package. By clicking on FileNew FileR Markdown in the menu bar of RStudio, a new R Markdown document will be opened. At this stage, we can receive a notification Install Required Packages, as follows:

image11.png

After confirming the required package installation, in a new pop-up window that appears, we provide a document title and the author's name (both optional but recommended), leave the other settings as they are, and press OK:

image6.png

Default R Markdown Document

In the previous section, we opened a new R Markdown document in RStudio. It looks as follows:

image16.png

We see that it includes the title, the author's name, the current date, and the default output format that we provided in the pop-up window when opening it. Then, it’s got some examples of the basic syntax used by R Markdown, such as adding and formatting code chunks, adding headers, inserting links, emphasizing text, and generating plots.

We're going to take a more granular look at various functionalities of R Markdown and their syntax. For now, let's save this default file and then render it in the selected output format (in our case—HTML) to see what it looks like.

To save the file, we click on FileSave As... in the menu bar of RStudio.

NOTE: the name of the R Markdown document that we provided earlier is not the same as the file name. We need to save the file in the project directory and then regularly save it from time to time (FileSave) while working with it.

To render the saved file in the selected output format (HTML), we need to press Knit in the toolbar of the file:

image8.png

Here is how our default R Markdown document looks in the HTML format:

image3.png

Text Formatting in R Markdown

Often, text constitutes the major part of a data science project. Hence, it's important to know how to format it in R Markdown to make it easy to read, efficient, and compelling.

If you want to learn how to use R for data analysis and data science and grow both your R programming and data science skills, consider the following beginner-friendly and exhaustive career tracks:

Headers

We can add various levels of headers to our R Markdown document by using the hash symbol (#). Here is the syntax:

# Header 1 (main title)

## Header 2 (section)

### Header 3 (subsection)

etc.

When rendered, the above headers will look as follows:

image20.png

 

 

 

 

 

Text Emphasis

R Markdown allows to add different types of emphasis to the text, such as making it italic, bold, strikethrough, superscript, or subscript, as follows:

  • *italic* or _italic_
  • **bold** or __bold__
  • ~~strikethrough~~
  • text^superscript^
  • text~subscript~

Below is how these types of emphasis appear in the rendered form:

image19.png

Lists

To create an unordered list, we use one of the following three syntaxes:

* Item 1* Item 2* Item 3

or:

- Item 1- Item 2- Item 3

or:

+ Item 1+ Item 2+ Item 3

In all cases, the rendered result will be the same:

image10.png

To create an ordered list, we use the following syntax:

1. Item 12. Item 23. Item 3

The rendered result will look quite the same, with an indentation added before each number.

Note that if we delete an item from an ordered list, add a new item to it, or just make an error in one of the numbers (e.g., if we write 20. instead of 2. in the above example), the numbers will be automatically corrected and shown as intended:

image14.png

Block Quotes

For block quotes, we use the > symbol before the first character of the text to be quoted:

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.

This will be rendered as:

image12.png

We add an empty line after a quoted block to escape it.n unordered list of 3 items

If we want to include a link as a direct path, we need to put the link path between the < and > symbols. For example, the following construction:

<https://www.google.com/>

will be rendered as:

https://www.google.com/

Instead, to anchor a link to a word or a short piece of text, we need to use the following syntax (using again the Google website as an example):

[Google](https://www.google.com/)

This will be rendered as:

Google

Images

To insert an image into our narrative, we use one of the following approaches:

  1. If we want to add an image from the Internet:

![Alt_text](image_url)

  1. If the image file is saved in the project folder where our R Markdown document is saved:

![Alt_text](image_file_name.extension)

  1. If the image file is saved on our computer but outside of the project folder:

![Alt_text](image_file_full_path)

Alt text provides short information about what it's on the picture and serves in those cases when a user is unable to see the image on the page, for whatever reason.

Let's see the first approach in action for a Pixabay picture, with the image URL https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:

![Network](https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg)

When we render the document, the picture is displayed:

image5.png

Breaks

There are various types of breaks in R Markdown:

  1. Line break—to start a new line. Implemented by ending the previous line with a backslash (\).
  2. Paragraph break—to start a new paragraph. Implemented by ending the previous paragraph with two spaces.
  3. Slide break—to start a new slide in the slide-based output formats (presentations) or a new section in all the other formats. Implemented by inserting a horizontal rule (***) into the document.
  4. Page break—to start a new page, in those output formats where it's applicable, e.g., in Microsoft Word. Implemented by inserting the command \newpage into the document.

Let's put the first three types of breaks into action. Below is a piece of the Lorem ipsum text with some R Markdown break formatting symbols added to it:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

***

Ut aliquet tristique nisl vitae volutpat.

Here is how it will be rendered in an HTML document:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.


Ut aliquet tristique nisl vitae volutpat.

Code Formatting and Executing in R Markdown

Code is another essential component of any data science project. In R Markdown, we can run code (and not only in the R programming language), display both code and its output, display only code and hide its output, display only output and hide the source code, etc.

The beginner-friendly career track R Programmer and skill track R Programming are helpful resources for learning, practicing, and sharpening your R coding skills.

Code Chunks

To format and run a block of R code in R Markdown, we enclose it in a pair of triple backticks, with the first triple backticks followed by an r in braces. For example:

```{r}
print("Hello, World!")
```

If we render our document without running the code, our code chunk will look as below:

image9.png

Code Language

When working with R Markdown, we aren't limited to using only R since this package also supports many other programming languages. To run a piece of code in another programming language, we provide the name of this language instead of the R in braces. Besides that, we may need to install and load some additional packages in the working R environment.

For example, to be able to use Python in R Markdown, we need to install and load the reticulate package that allows two-way communication (like creating and accessing variables) between Python and R in the same R Markdown document.

Let's rewrite the piece of code from the previous section in Python (after installing and loading the reticulate package):

```{python}
print("Hello, World!")
```

image9.png

Code Chunk Execution

To execute a code chunk or the selected lines of it when working with R Markdown within RStudio, we click on the Run button on the document's toolbar and select the necessary option from the drop-down list:

image21.png

In the above picture, we see that each run option has its shortcut that we can use instead of opening every time the drop-down list.

Code Chunk Naming

While not mandatory, it's a good practice to name code chunks. It can be useful in many cases: for referencing code chunks throughout the document, code debugging, switching between code chunks, etc. Naming code chunks becomes particularly important if we work with a long document that contains a lot of code chunks.

We add the name of a code chunk in braces, right after the language name, and separate it with a white space. The name of a code chunk must not contain white spaces.

In the below example, we added the name hello_world to the chunk:

```{r hello_world}
print("Hello, World!")
```

Code Chunk Options

Code chunk options allow us to take control over code evaluation, output, decoration, cache, animation (if applicable), and plots (if applicable)—all these for each individual code chunk. We can add multiple chunk options to the same code chunk. In terms of syntax, we put chunk options in braces right after the code name (if available; otherwise, after the language name), separated from it and between themselves by a comma.

There are many chunk options available in R Markdown. Each of them has a default value, but when we decide to use them, we most probably want a value different from the default one. Let's look at the most popular chunk options and their values that could be of interest to us:

  • echo=FALSE—the code itself will not be shown in the final document, only its outputs.
  • eval=FALSE—the code in the code chunk will not be run.
  • include=FALSE—the code chunk will be run but not included in the final document.
  • results—the default value is "markup"; other values are:
    • "hide"—the code output will be hidden in the final document
    • "hold"—the code output will be shown with a delay, only after the whole code chunk is executed
    • "asis"—the code output will be passed through without reformatting.
  • message=FALSE—the messages produced by the code will not be shown.
  • error=FALSE—the errors produced by the code will not be shown.
  • warning=FALSE—the warnings produced by the code will not be shown.
  • highlight=FALSE—the code will not be highlighted in the final document.
  • prompt=TRUE—the > symbol will be added at the beginning of each code line shown in the final document.

Below are some examples of code chunks that were first run in R Markdown in RStudio and then rendered in the final document:

Code in R Markdown:

image15.png

Output in the final document:

image17.png

Inline Code

With inline code, we can directly insert short pieces of code into the text of our R Markdown document—they will be executed, and their outputs will be shown embedded into the text. The syntax of inline code is r <code>.

Below is a simple example of a text containing inline code:

There are `r 1+6` colors of the rainbow.

and how it is rendered in the final document:

There are 7 colors of the rainbow.

In practice, inline code is used for aggregating information about the data and helps avoid errors that can easily happen if we insert the numbers manually or if the data changes.

Plotting in R Markdown

Plotting in R Markdown implies running code that generates plots. Hence, everything that we've discussed so far about code formatting and executing in R Markdown, except for inline code, also applies to plotting. The main difference is that the output of such code will be graphics rather than just text and numbers.

The skill track Data Visualization with R will help you develop the skills needed to analyze and plot data in R and, hence, tell better data-driven stories.

To customize plots in R Markdown, like in regular R, we use the tools of R data visualization packages, as well as the plot() function of the base R.

However, to control plotting behavior in an R Markdown document, we can make use of chunk options that are related only to plotting. The majority of them are quite specific and, therefore, outside of the scope of this "getting started" tutorial. Let's thus take a look at some basic chunk options that can be helpful when plotting in R Markdown:

  • fig.show—the default value is "asis"; other values are:
    • "hide"—the plots will be generated but not included in the final document
    • "hold"—the plots will be shown with a delay, only after the whole code chunk is executed
    • "animate"—all the plots of the code chunk will be combined into an animation.
  • fig.width—the plot width in inches, 7 by default.
  • fig.height—the plot height in inches, 7 by default.
  • fig.align—the way of aligning plots in the final document, can be "left", "center", or "right".
  • fig.cap—a figure caption represented by a character string.
  • fig.path—a path to the directory where the plot files created by the code chunk should be stored.
  • fig.ext—the extension of the plot files created by the code chunk.

Below are some examples of using plotting-specific code chunks when plotting in R Markdown, including the source code and the rendered output:

Code in R Markdown:

image1.png

Output in the final document:

image4.png

Output Formats

Until now, we have considered only the HTML document (html_document) as an output format for the final document. However, R Markdown offers many other output formats, including Microsoft Word, Microsoft PowerPoint, PDF, interactive R notebooks, dashboards, etc.

For example, the output formats available in R Markdown for creating documents include html_document, pdf_document, word_document, github_document, html_notebook, html_vignette, etc. Instead, for creating presentations, we can use the following output formats: powerpoint_presentation, ioslides_presentation, slidy_presentation, and beamer_presentation.

To set an output format for our R Markdown document, we assign the corresponding value to the output setting in the document header (also known as the YAML header, where YAML stands for yet another markup language). For example, for our working R Markdown document, the output format is set to html_document, which is also the default output format in R Markdown:

image2.png

To change it, we substitute html_document with the necessary output format (pdf_document, word_document, powerpoint_presentation, etc.). Now, when we press Knit in the toolbar of the file, we'll render our document in the selected output format.

Publishing R Markdown Documents

To publish an R Markdown document, we click on FilePublish in the menu bar of RStudio and select where we want to publish it:

image18.png

Then we follow further instructions that will depend on our previous choice and press Publish. Now, our document is ready for sharing with our collaborators.

Conclusion

To wrap up, in this article, we learned how to get started with R Markdown. First, we defined what R Markdown is and what it's used for. Then we discussed how to install R Markdown, how to format text and its various components with it, how to format and run code, how to generate plots, which output formats R Markdown offers, how to render a working document in one of those formats, and how to publish the final document for further sharing it with colleagues.

To get some hands-on practice using R Markdown, check out our Reporting with R Markdown course, which will help you reveal insights from data and author your findings as a PDF, HTML file, or Shiny app.


Photo of Elena Kosourova
Author
Elena Kosourova

IBM Certified Data Scientist (2020), previously Petroleum Geologist/Geomodeler of oil and gas fields worldwide with 12+ years of international work experience. Proficient in Python, R, and SQL. Areas of expertise: data cleaning, data manipulation, data visualization, data analysis, data modeling, statistics, storytelling, machine learning. Extensive experience in managing data science communities and writing/reviewing articles and tutorials on data science and career topics.

Topics

Start Your R Journey Today!

Course

Reporting with R Markdown

4 hr
36.2K
R Markdown is an easy-to-use formatting language for authoring dynamic reports from R code.
See DetailsRight Arrow
Start Course
Certification available

Course

Introduction to R

4 hr
2.7M
Master the basics of data analysis in R, including vectors, lists, and data frames, and practice R with real data sets.
See MoreRight Arrow
Related

40 R Programming Interview Questions & Answers For All Levels

Learn the 40 fundamental R programming interview questions and answers to them for all levels of seniority: entry-level, intermediate, and advanced questions.
Elena Kosourova's photo

Elena Kosourova

20 min

Navigating R Certifications in 2024: A Comprehensive Guide

Explore DataCamp's R programming certifications with our guide. Learn about Data Scientist and Data Analyst paths, preparation tips, and career advancement.
Matt Crabtree's photo

Matt Crabtree

8 min

Top 32 AWS Interview Questions and Answers For 2024

A complete guide to exploring the basic, intermediate, and advanced AWS interview questions, along with questions based on real-world situations. It covers all the areas, ensuring a well-rounded preparation strategy.
Zoumana Keita 's photo

Zoumana Keita

15 min

Avoiding Burnout for Data Professionals with Jen Fisher, Human Sustainability Leader at Deloitte

Jen and Adel cover Jen’s own personal experience with burnout, the role of a Chief Wellbeing Officer, the impact of work on our overall well-being, the patterns that lead to burnout, the future of human sustainability in the workplace and much more.
Adel Nehme's photo

Adel Nehme

44 min

Becoming Remarkable with Guy Kawasaki, Author and Chief Evangelist at Canva

Richie and Guy explore the concept of being remarkable, growth, grit and grace, the importance of experiential learning, imposter syndrome, finding your passion, how to network and find remarkable people, measuring success through benevolent impact and much more. 
Richie Cotton's photo

Richie Cotton

55 min

Visualizing Climate Change Data with ggplot2: A Step-by-Step Tutorial

Learn how to use ggplot2 in R to create compelling visualizations of climate change data. This step-by-step tutorial teaches you to find, analyze, and visualize historical weather data.

Bruno Ponne

11 min

See MoreSee More