6.208
Writing Documents with Markdown

Preface

This tutorial presumes that you have R and R Studio installed, or that you have an account on rstudio.cloud. If you do not already have R and/or R Studio you will need to download and install them. You must first install R from R Project and then the R Studio IDE from R Studio.

Introduction

This lesson introduces the process for writing documents (essays, memos, reports, and scientific papers) using a combination of markdown and code. It uses the R Notebook as its foundation, although markdown is a general language and is supported by numerous other platforms, including Jupyter Notebooks and Google Docs.

There is much more to creating R Notebooks than is shown here. Here we focus on writing documents rather than dynamic data reports, data analyses, or data analytics journals. The documents we will show you how to write will include headers, paragraphs, simple formatting, links, images, embedded web objects, simple R code, and equations. The resulting document will be in PDF and HTML.

R Studio Projects

A project is a collection of markdown files, scripts, images, and data files. Projects allows all files, including data files, to be managed as a single unit, shared, and version controlled using services such as git and GitHub. You should always do your writing in an R Project. See Lesson 6.202 Working with R Projects on how to create projects in R Studio.

Literate Programming

From the perspective of information science, a document is an aggregate of information objects, some of which are created programmatically.

Building an R Notebook

Chunks

This will show a verbatim inline R expression `r 1+1` in the output.

```{r echo=F}
```

Embedding R Code {embR}

A code chunk (sometimes also referred to as a code fence) for R code looks like this:

Code Chunks with Line Numbers

if (TRUE) {
  x <- 1:10
  x + 1
}

##  [1]  2  3  4  5  6  7  8  9 10 11

In general, a code chunk starts with the language followed by an optional name for the chunk. The name (or chunk label) is useful for quick navigation and for referencing within the document. In R Studio, it can be used for quickly jumping to a section of code.

Jumping to A Chunk by Name

Headings

Common R Markdown

See the R Markdown Reference Guide for a complete list of markdown elements.

Knitting

Knitting an R Markdown document generates a markdown document which is then converted to a document, commonly PDF or HTML. This process is often called knitting or rendering; it is essentially a form of compilation. During the knitting process, code chunks and inline code statements are executed and any output is embedded in the result document, unless chunks are marked as not being evaluated or not being included.

Embedding Code Inline

Custom Formatting with Embedded HTML

Embedding LaTeX Equations

Embedding Images

Embedding Hyperlinks and URLs

Tutorial

The tutorial below demonstrates how to create a Notebook in R Studio and add code chunks.

Link to Video: TBD

Summary

---

Files & Resources

All Files for Lesson 6.208

---

References

Xie, X., Dervieux, C., Riederer, E. (n.d.). R Markdown Cookbook. Available at bookdown.org

Overview of R Markdown

R Markdown Cheat Sheet

Wikipedia: Literate Programming

Embedding Verbatim Code Chunks in Markdown

Errata

None collected yet. Let us know.