Creating the Document

You can select R Markdown when you create a new file. If you are typing in a plain text file, you can save it with “.Rmd” as the file type.

The file should start with a header that defines some key characteristics of your file. It should look something like this:

---
title: "Book of Shadows"
author: "Bridget Bishop"
date: "8/28/2020"
output: pdf_document
---

There are many options to update the format of the document you produce. A few examples are the css to use for style, how to number your section headers and including a table of contents. Like many other things that can be done using R, it is completely customizable. It is important to insert white space into the header properly. Some parts, like the formatting, will be tabbed over, others will not be. The header then will then look something like this:

---
title: "Book of Shadows"
author: "Bridget Bishop"
date: "8/28/2020"
output: 
  pdf_document:
    toc: true
    number_section: true
    css: "style.css"
---

For a more complete list of options, check out the last page of this reference from RStudio.

Markdown Language

Once you have the header set up, you are ready to start creating your document. You can start writing right away! In order to get formatting like italics and inserting pictures, you need to use the markdown language. Don’t worry! It’s not another coding language you need to learn. Markdown is a set of formatting tools for you to use without taking your fingers off of your keyboard! It uses special symbols to denote the kind of formatting to use.

These are the ones you would likely use most often:

• Italics are denoted with a single * and bolded words are highlighted with two.
  
• To make a link within the text (mostly for HTML pages), the words that the reader can click on will be contained in square brackets, [], and the web address will be contained in curved brackets, ().
  
• To divide your text into sections, you can use the # symbol to create section headers. The more you use in one line, the further into the hierarchy the section headers will be.
• To insert an image, you use the symbols ![](path/to/image.jpg). Inside the square brackets, you can include settings for your image like width and height.
• Math equations can be inserted by wrapping the LaTeX mathematics typesetting code with $’s.

For a more complete list of options, check out the first page of the reference from RStudio.

Including Code

The most important reason to use R Markdown rather than any other typesetting program is that it is capable of running R within your documents! When building the PDF or HTML version of the document, R will run the code you have included and provide the proper output; images, values, tables, and all! It doesn’t even have to be R code! In RStudio, there is an “Insert” button in the text editor window that includes options for Python, SQL, and plain Base language, just to name a few. Choosing one of these options will result in a code chunk being inserted into your document that looks like this:

```{r label}
#code to run
```

You can insert the exact same code that you would normally put into R and it should run the same way. Being honest, there might be a few errors that have to do with continuity within your document. Double check that everything you need is defined properly!

Code chunks themselves have a lot of options to control how the output is displayed as well as the chunk itself. These are listed after the label of the R chunk, separated by commas. The ones I use most often are as follows:

• eval: Controls whether the code is run at all when the document is built.
• include: Sets whether the code chun itself is displayed in the document. Normally this is automatically set to FALSE.
• message: Determines if any messages from the code will be displayed in the document. I would recommend setting this to FALSE if you have a lot of warnings, but your code still runs properly.
• cache: Definitely set this to TRUE! This will keep track of the results of code that has been run so that it doesn’t need to run it again everytime you build your document.