So let's learn more about R Markdown. I encourage you to review the R Markdown website by RStudio. There is several links, Get Started, Gallery, Formats, and Articles. Start with the Get Started. There's some information here, including some embedded videos, that will help you learn about R Markdown. There's also some links here for the cheat sheet and the reference guide. I encourage you to take a look at this overview on how R Markdown works. And there's a nice little diagram at the bottom of this page that shows we're going to be starting with an R Markdown file. And then we're going to be using the knitr package to produce a simplified markdown file, which is then used by pandoc. And we talked about pandoc in an earlier lesson as the universal document converter. And so pandoc is the thing that actually changes your R Markdown file into the different document formats that you're interested in. On this website you can also take a look at the Gallery. And the gallery has a number of things here and for example, documents, for example, things in HTML, Microsoft Word, handout styles, as well as PDF. There are interactive documents that you can create, which are wonderful if you want to publish things on a website. As well as other information here on dashboards. We're also going to be talking about presentations, specifically you're going to learn ioslides and Slidy, but I'm going to briefly mention the Beamer option as well as the reveal.js package. And finally, you'll get a brief taste of how to make a book using R Markdown. In the website here there's also links for the different formats, and we're going to refer to these several times during the upcoming lessons including things for options on HTML documents, PDF documents, Word documents, as well as the different slide presentation formats. So let's do a quick overview of the components contained in an R Markdown document. At the top of the R Markdown document you're going to have document metadata. The metadata is contained in a YAML header and that has information about the document, various parameters, formatting options, and other options that can be customized. After the YAML header comes the body of the document, the rest of the document will consist of mainly plain text. In this plain text will contain the content of your document along with some R Markdown syntax. And for this course it's all going to be based on Markdown. You're also going to likely have some programming code, these are called code chunks. For this course you're going to be learning the R language, but in our studio using the R Markdown package there's options for including other computer languages. And you may also have other embedded objects such as figures, images, photos, pictures, tables, videos and animations, equations, references, or footnotes. So let's start at the beginning with the YAML document header, that contains your document's metadata. What is document metadata? Every document, and really file for that matter, you create has metadata. Metadata's often referred to as data about data. In other words, metadata's the information about your document or file, it's not actually the data within your document. So let's see an example. On a Windows machine you can open the file explorer, find a file and right-click on it, and choose Properties. In the Properties menu if you click on Details you can see all of the metadata about your document. With a Microsoft Word file you get information like the authors, when it was last saved, sometimes the program name of the software, when the document was last created. You get some information on whether a template was used, how many paragraphs, the word count. And you get information here on file size. Besides Microsoft Word Documents you can look at other file types. For example, an image file like the one shown here. If we click on Details we get other kinds of information. For example, the image dimensions, the width and the height, the bit depth, and we also get the same kind of stuff that we saw before like the file name and the date created and so forth. So when we create an R Markdown document we're going to have direct control over this metadata through the information that's contained in the header of the document. This header information is provided and structured using YAML. So what is YAML? YAML stands for yet another markup language or YAML ain't markup language, depending on who you ask. You can learn a lot about YAML by simply searching the Internet. You can also visit the official YAML website but their website's aimed mainly at programmers and it's not very user friendly. However, the yaml.org website does offer some insight into how many different programming languages and platforms support YAML besides R Markdown. Technically, it is possible to create an R Markdown file without a YAML header. But for this course we'll always have some information contained and defined within the YAML header. We're going to be using the YAML header to define the parameters or options used by R Markdown, R Package to render the final document. We're going to talk about the render function in future lessons, but for now, just understand that the information contained at the YAML header is used as instructions and input parameters for creating the final document. So let's create a GitHub repository for this next exercise. Go ahead and log into your GitHub account and create a new repository. Module2_rmd1. Go ahead and type in a description. New Rmarkdown document. And we're going to initialize this with a README. Click Create repository. Now, that you've got your new repository created, go ahead and click on the Clone or download, and we're going to copy the URL to the clipboard just like we did in the first module. If you don't have it open, go ahead and open RStudio. We're going to create a new project, and again, we're going to use Version Control with Git. This is where we need to paste in the repository URL that we just copied. So we should now have a project directory named Module2_rmd1. This should be created as a subdirectory for the folder that you created for this course, for example, RepTemplates. So once you've got everything defined click Create Project. Again, the window pops up briefly saying that it's cloning a copy of your repository. Now, that you've got a new RStudio project created, let's go ahead and create a new R Markdown file. Click on File, New file, R Markdown. And put in a title for your document. For example, Module2- R Markdown Document 1. And put in your author name. We're going to stay with the default HTML format, and click OK. So when your document opens you'll notice that there's information contained at the top, this is your YAML header. And you will see that the information we typed in in the previous menu like the title, the author, and even the output format, was created and inserted up here at the top. If you'll notice that there's a tab called Untitled and next to it is a little icon with a red circle that's kind of hard hard to read, but inside the red circle there are three letters for rmd, this is the R Markdown. But let's go ahead and save it. You can either click the little save icon or click File and click Save, and go ahead and give a name for your document, for example, module2_rmd1, and click Save. And you'll notice that the title changes in the tab and it now has your filename. So let's take a look at the very top of the document. It starts with three dashes. Those three dashes indicate that this is the beginning of the YAML header. In this content, you're going to see the title, the author, the date, and the output. And then after the output there are three more dashes, this indicates that that is the end of the YAML header. The words title, author, date, and output are all YAML keywords, and these are parameters or options used by the render function in the R Markdown package to compile and create the final document. After each keyword there's a colon followed by the input that you gave it. For example, your title input is in quotation marks and it says, "Module2 R Markdown Document 1". Similarly, on the next line you have a keyword author followed by a colon and then your name in double quotation mark. Likewise, you have the same thing for the date. Currently, though, the last line of the YAML header has the keyword output html_document. And this was defined when we first created the new file R Markdown document. We're going to be learning a lot more about this YAML keyword for output because this is where we define the parameters for customizing the various output formats that we want. For now, watch what happens when we select different knit options. First, let's knit to HTML. When you do this your document should open in the Viewer window which is shown on the bottom right. If for some reason your document does not appear in the Viewer window check your knit options, click the gear icon next to the knit. And notice there are two different options here, one is Preview in Viewer Pane, which I'm doing currently, if click Preview in Window, it simply moves it to a new separate window. For now, I'm going to switch it back to Preview in Viewer Pane. So now, let's knit to Word and create a docx formatted file. If you click the little arrow next to the knit button you'll see the different options. And if we do click Knit to Word, you'll notice that a couple things happen. The YAML header was changed automatically, and this is one example of how changing the options in your YAML header directly affects the output produced from your R Markdown document. And here is the example of the document shown in a different kind of viewer window for Microsoft Word docx format. Optionally, if you have LaTeX installed in your computer you can also try Knit to PDF. And again, this will open in any window to preview the PDF document. And your YAML header will change once again and include pdf_document as an option for the output. Here is a preview of the PDF document. We're going to be adding and removing more YAML keywords as we go through this course. Go ahead and keep this R Markdown file open for the next lesson.
