3 R Markdown Guide

3.1 What is Markdown

Markdown is an interactive system of text formatting that is a useful way to produce documents when using data and statistics. If you have ever produced a graph in Excel to put in a Word document, what do you have to do? Create the graph in excel, copy and paste it into Word, and probably redo the formatting to make it fit with the text. And if you decide to change the graph, you have to start all over again, adding each feature manually. R Markdown allows us to create the graph in our document using the R language, and automatically formats it. Over a lifetime of writing data-driven documents, it can save significant time and reduce the frustration of formatting and reformatting images. R Markdown is designed to make life easier for you.

By the way, everything you’re reading is written in R Markdown. I never could have completed this book if I had to manually insert all the graphs and functions that I will show you this semester. For instance, I probably saved 10 minutes on just this plot.

To try and explain Markdown a bit better, I’ll quote from Cosma Shalizi

You are probably used to word processing programs, like Microsoft Word, which employ the “what you see is what you get” (WYSIWYG) principle: you want some words to be printed in italics, and, lo, they’re in italics right there on the screen. You want some to be in a bigger, different font and you just select the font, and so on. This works well enough for n00bs but is not a viable basis for a system of text formatting, because it depends on a particular program (a) knowing what you mean and (b) implementing it well. For several decades, really serious systems for writing have been based on a very different principle, that of marking up text. The essential idea in a mark-up language is that it consists of ordinary text, plus signs which indicate how to change the formatting or meaning of the text. Some mark-up languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup; others, like the language called Markdown, are more subtle.

We’ll explore that subtlety below

3.2 Getting Started

Let’s start with the basics. How to create an R Markdown document.

  1. Open R Studio
  2. Click on the upper left icon with white document and green plus sign.

  1. In the drop down menu there is an option for R Markdown, click on it which will bring up a new screen.

4. For now, let’s create our Markdown documents as PDFs. Enter any title you want and your name.

  1. Once you click OK, your new markdown will open with some sample code inserted. Let’s see what a finished R Markdown document looks like with that preset code.

  1. The arrows highlight some important features to get us started.
  1. This is the knit button, which you’ll meet in a minute.
  2. This is code chunk. Much of what you write in a Markdown will just work as text, unless you put it in a code chunk. A code chunk starts with three ` (which are named back quotes, should be to the left of the numbers on your keyboard) and {r}. To close a code chunk you just put the three backquotes.That tells R that you’d like to write something in code, like printing a table or a graph. Otherwise, a Markdown document is just a written document and you can say something like 2 + 5 without it trying to create interpret that as a math statement.
  3. This is a heading. The reason that it shows in blue is because it isn’t just text, it has something added to it - the two hashtags that precede it means it will print larger and bold
  4. This is another code chunk
  5. This will print as plain text
  6. This final bit of text introduces an important feature of Markdown documents. if you insert echo=TRUE to your code chunk, the code you use will appear as part of the document, and if you write echo=FALSE it will not. If you’re writing a document that will be printed for the public, you might not want your code to show. If you’re turning in an assignment to your teacher, they’ll probably want to see your code.
  1. To execute the Markdown document you need to press Knit, which will be in the upper middle of the screen. The first time you create a Markdown document as a pdf you’ll need to have the TimyTex package installed, so you will need to run this bit of code in R Studio tinytex::install_tinytex(). Enter that on the command line and execute it.

  2. After you click Knit you’ll need to tell R where you want to save the document. If this was a part of an assignment you’d probably want to use a file you have for your class projects. For this document the desktop or downloads file will work. But anytime you Knit a Markdown document it will be saved.

  3. Voila, you have created a Markdown document!

We’ll talk a lot more about the ways we can use R with Markdown this semester, and we’ll practice inserting code and graphs. For now, we need to focus on the text aspect of R Markdown. Some of this has been previewed above, but here I list many of the ways you can format your text in a Markdown document.

3.3 Markdown Format Cheat sheet

This section describes and displays many of the most common formatting commands in Markdown.


3.3.1 Headers

# Heading One (h1)

## Heading Two (h2)

### Heading Three (h3)

#### Heading Four (h4)

##### Heading Five (h5)

###### Heading Six (h6)
headings

headings


3.3.2 Text Style

With Markdown, it is possible to emphasize words by making them *italicized*, using *astericks* or _underscores_, or making them **bold**, using **double astericks** or __double underscores__. 

Of course, you can combine those two formats, with both _**bold and italicized**_ text, using any combination of the above syntax. 

You can also add a strikethrough to text using a ~~double tilde~~.

With Markdown, it is possible to emphasize words by making them italicized, using asterisks or underscores, or making them bold, using double asterisks or double underscores.

Of course, you can combine those two formats, with both bold and italicized text, using any combination of the above syntax.

You can also add a strike through to text using a double tilde.


3.3.3 Lists

3.3.3.1 Unordered

* First item
* Second item
* Third item
    * First nested item
    * Second nested item
  • First item
  • Second item
  • Third item
    • First nested item
    • Second nested item

3.3.3.2 Ordered

1. First item
2. Second item
3. Third item
    1. First nested item
    2. Second nested item
  1. First item
  2. Second item
  3. Third item
    1. First nested item
    2. Second nested item

3.3.5 Images

Insert images in a similar way, but add an exclamation mark in front of square brackets [ ], and the image file name goes in the parentheses ( ).

![alt_text_here](image_file.png)

The alt text appears when the image cannot be located, or is read by devices for the blind when the mouse hovers over the image. It

It is common practice to place all of the image files in an “assets” or “images” folder to keep your directory tidy. You can reference files inside a folder using the folder name and the forward slash:

![](images/shutterstock_professor.jpg)
credit: Shutterstock, but why?

credit: Shutterstock, but why?

Pictures are posted in their default size, which sometimes may be too large or small. If you want to scale them down or up, add { width= } to the end of the command.

![](images/shutterstock_professor.jpg){ width=50% }


Or you can link directly to an image online using the URL address of the image:

![](https://cdn-image.travelandleisure.com/sites/default/files/styles/1600x1000/public/1507062474/hotel-everest-namche-nepal-mountain-lodge-MOUNTAIN1017.jpg)


3.3.6 Tables

| Title 1          | Title 2          | Title 3         | Title 4         |
|------------------|------------------|-----------------|-----------------|
| First entry      | Second entry     | Third entry     | Fourth entry    |
| Fifth entry      | Sixth entry      | Seventh entry   | Eight entry     |
| Ninth entry      | Tenth entry      | Eleventh entry  | Twelfth entry   |
| Thirteenth entry | Fourteenth entry | Fifteenth entry | Sixteenth entry |
Title 1 Title 2 Title 3 Title 4
First entry Second entry Third entry Fourth entry
Fifth entry Sixth entry Seventh entry Eight entry
Ninth entry Tenth entry Eleventh entry Twelfth entry
Thirteenth entry Fourteenth entry Fifteenth entry Sixteenth entry

3.3.7 Blockquotes

3.3.7.1 Single line

> The purpose of life is to contribute in some way to making things better. - Robert F. Kennedy

The purpose of life is to contribute in some way to making things better. - Robert F. Kennedy

3.3.7.2 Multiline

> Every time we turn our heads the other way when we see the law flouted, when we tolerate what we > know to be wrong, when we close our eyes and ears to the corrupt because we are too busy or too > frightened, when we fail to speak up and speak out, we strike a blow against freedom and decency > and justice.
>
> – Robert F. Kennedy

Each time a man stands up for an ideal, or acts to improve the lot of others, or strikes out against injustice, he sends forth a tiny ripple of hope, and crossing each other from a million different centers of energy and daring, those ripples build a current that can sweep down the mightiest walls of oppression and resistance.

-Robert F Kennedy


3.3.8 Horizontal Rule

---