In module three, we're going to focus on changing the parameters available for each document format, to customize the style, appearance, and layout of our documents. In this lesson, we're going to explore the options available for customizing HTML documents. We will be referring throughout the this lesson to the information contained in R Markdown website for the HTML format. As we begin this module, let's create a new GitHub Repository. Log back into your GitHub account, and create a new Repository called Module3. And we'll type in the description Module 3 of the Reproducable Templates Course. And for this repository, we do want to initialize it with a a read me file. So click that box and then click Create Repository. Once your repository is created go ahead and open our studio. From here let's create a new project. Click File > New Project. We're going to do this with version control using Git. And we need the repository URL. So go back to your GitHub account for Module3 repository. And click on the button that says Clone or download. And copy the URL to the clipboard. Paste this URL in to the window shown here in our studio. Your Project directory name will be Module3 and it should be created as a sub-directory of your Rep templates folder for this course. Click Create Project. So now that we've created the project and we're connected to GitHub via Git. Let's create a new R Markdown document. In RStudio, click File > New File > R Markdown [NOISE]. We're going to select Document for HTML format, put in a title, [NOISE] Module3 HTML Document, and click OK. Let's start by customizing the appearance and style of the HTML document. Back at the website for the HTML documents format, if you click on the link here for appearance and style, you'll notice that there are several options that control the appearance of your HTML documents. For example, you can define a theme. And the themes are available based on the Bootswatch theme library. And you can learn more at their website, and the link is shown here. You can scroll through here to see what the different themes look like. For example, suppose we want our document to look like the Cerulean theme. We can click on it here and see a preview of what this style and formatting is going to look like. If we want to add this theme to our HTML document, go back to rstudio, and we're going to edit the YAML header. For each HTML document option that we change, we're going to put these on separate lines n the YAML header with the keyword followed by a colon and then the option setting. We're going to go ahead and set the team to cerulean and we're going to change the highlight option for highlighting code syntax. And for highlight we're going to choose that option Kate. Each option is indented by two spaces. Go ahead and click Save, and we'll call this HTML document. And we're going to save it here in the folder for Module3. Then click knit to HTML to see the changes. You'll notice here that all of your headers are in a blue font. Let's try another one. There's another theme that we can look at, called yeti. And we're going to change the highlight to espresso. Press save, knit to html, and you can see the changes. You'll notice that the background has changed slightly, the font has changed, and the code and the output shown here is in a different colored font. Another way to make changes to the appearance and style of your HTML documents is to use cascading style sheets or CSS. So let's create a simple CSS file and we will use it to apply those formatting changes to your HTML document. To create this file, In R Studio click on File > New File > Text File. This is just a simple file with text commands. We're going to be creating CSS definitions. The first one we're going to call is something called nextsteps. So we're going to put in the following CSS commands. Next steps is shown here, and it's going to define a font color of blue. We're also going to create an option called emphasized which is going to make our font-size a little bit bigger. The 1.2em shown here will make it roughly 1.2 times larger than the standard font. So let's go ahead and save this. We're going to save it and we're going to call it my CSS. And go ahead and put in the period followed by CSS in the end. This is so the computer and R will recognize it as a CSS file. Click Save. To use this, we need to go back to our HTML document. And we're going to change the YAML header options. We're going to remove the theme and the highlight. This time we're going to add an option for the CSS. So we type in CSS, followed by the name of the file that we just created. So now that we've got the my CSS file defined here in our YAML header, we need to apply the formatting where we want it in the document. So let's add it to just the first section of the document, defined by the level two header shown here with the two hash tags for R Markdown. In order to use these, we need to add two curly brackets, an open and closing curly brackets, followed by the options we just created in the CSS. First we type in #nextsteps and we're also going to include the emphasized option. Go ahead and save this and then click Knit to HTML to see the changes. When this opens, you'll notice that not only has the header changed to a blue font, but this whole section of text is now also blue. And in a larger font that was defined by the font size 1.2. This was specified in the mycss file. Your formatting options are pretty much limitless when applying CSS to an HTML document. Completely learning CSS is beyond the scope of this course, but there are hundreds of helpful websites for learning this. A good place to start is the W3 School's website. Let's try some other customization options. In module two, we saw that we could change the figure width and height settings to affect the size of a figure created within an R Code junk. You can also affect the sizes of your figures for the entire HTML document, and you can set these options in your YAML header. So let's edit the YAML header, and we'll add options for figure width and figure height. So at the top, shown here, we're going to get rid of the CSS for a moment. And we're going to add in figure_width, and we'll set that to 5. And figure height, and we'll also set that to 5. Adding these two options in your document makes it so that the figures produced will be roughly five inches by five inches for each plot shown. Before we knit this document, though, let's add another plot to our document. In the first code chunk here that says summary cars, we're going to change that instead of summary to plot. Now click Save. And we'll knit to HTML. You'll notice now that the plots are a little bit smaller than they were before. Previously, the default figure width was seven, and the height was five. These heights and widths are in inches. Another way to access the rendering options for your document is to click on the little gear-shaped icon next to the knit button. We're going to select output options. Under the figures tab shown here, you'll notice it does say that the default figure width in inches is 5 and the default figure height in inches is also 5. We can change these, let's change them to 6 and 6, and click OK. When we do this, you'll notice that the YAML header was updated automatically. It now says that the figure height and width are each 6. Click save and knit to HTML if you would like to see the changes. The figures are now slightly larger than they were before. Another option that we can add to an HTML document is a table of contents. But before we test adding a table of contents, let's add just a few more sections to the HTML document. For example, we can add the following two sections. One with a bulleted list, and one with a simple equation. So we can add these two sections to our document, a short list shown here, and a simple equation. You'll notice that we now have four level two headers in our document. When we create the table of contents, we should end up with these four sections listed in the table of contents. We can add the table of contents either by editing the YAML header directly using the toc keyword or we can click on the little gear icon for output options, and in the general tab there is a box here for include table of contents. Go ahead and click that box, and click OK. You'll notice that the YAML header has been updated automatically and now includes the keyword toc followed by a colon and yes. Click save and knit to HTML to see the results. Now, the top of our document has four bullets. Each one is a hyperlink to that section of the document. For example, if I click on the short list, it takes you to the bulleted list. So the table of content becomes a navigation tool for your newly built HTML document. Another really neat table of contents to try out is a floating table of contents. So let's add the YAML header and add one more option for toc float, and we'll set it equal to true to take effect. Type in toc_float followed by true. Let's click save, and knit to HTML to see the results. You'll notice now instead of the table of contents being a bulleted list at the top, we actually have this little toggle menu that's shown at the top. It's a little hard to see here in a viewer window inside RStudio. So let's go take a look at this file in your repository directory, For html documents. And let's open this in a separate browser window. Now you can see that the table of contents does indeed float and is shown on the left. If we click on these, we can now navigate through our document. The table of contents, by default, tracks and lists level one, two and three headers. So let's go back and we're going to add a couple of level one and level three headers. So we've added a level one header right here at the top for Module 3 HTML Document. And we've also added a couple of level three headers shown here that simply says here is a plot of the car dataset and a plot of the pressure dataset. Let's click save and knit to HTML to see the results. To fully appreciate these added changes, let's go back to your browser window, and you can view this document shown here. Now, when I click on each piece, you'll notice that the lower level headers are nested within the higher level headers until you click on them, and then the lower level headers are shown. For example, if I click on including plots, it then shows plot of the pressure dataset, which was a level three header nested underneath this level two header. Let's look at one more option we can customize for HTML documents. In a previous lesson, you saw how setting the code junk option, echo equals true, or echo equals false, could be used to show or hide the code in the final document. There's one more option called code folding. Let's add that option to the YAML header. And we're just going to append this to the other options that we've already got set. We're going to set the code_folding option initially to hide so that it will hide the code unless the reader clicks the resulting button to show the code. So let's type in this following option, code_folding, followed by a colon and then we type in hide. Let's save this and knit to HTML to see the result. When this completes, you're going to notice the following three things. First, there's a button shown at the very top of the document that says code with a down arrow next to it. If you select this, you can either choose to show all, or hide all of the code. You can toggle this back and forth to see the changes. Second, the only code that was shown or hidden was for the first code chunk option for the plot of the cars dataset. This is because the echo option for this code chunk was set to true. If you scroll down, you see that the echo option for the plot pressure code chunk was set to false. For code chunks that have echo set to false, they will never be shown even when the code folding option is used. If you want to use code folding, I'd suggest that you set echo equal to true for all of your code chunks. And then let the user decide whether to show or hide the code as they wish when they read your final HTML document. The final thing to notice is that for the first plot of the cars dataset, you can also click on a button that says code to show or hide this code chunk only. We're going to add one more option to the YAML header to actually keep a Markdown document. Technically, in RStudio, you're creating an R Markdown document. When the document's compiled, each file is first converted to a basic Markdown document that then is used by Pandoc to compile into your final desired format, in this case, an HTML document. You can actually choose to keep this interim plain Markdown document. To do this, we need to set an option keep md to true. So scroll back up to the HTML document section here in the YAML header, and we're going to type in keep_md and set that to true. Let's click save and knit to HTML. If we take a look at the files tab, you'll notice that in addition to our html_document.Rmd in the resulting HTML file, we now also have a file called html_document.md. It turns out that GitHub was actually built to natively display these plain Markeddown files. I'm going to show you a demonstration of this when we upload everything to GitHub next. Before we do that, let's make one more minor change. Let's save this current HTML document to another file name. Click on File, Save As, and this time instead of HTML document, we're going to call this githubmd. We're actually going to create a GitHub mark down document, and click Save. So we're going to go back up, and we're going to edit the Yamel header. This time instead of HTML document, we're using md document for markdown document and specifically, we're going to create a GitHub variant, this is going to be compatible with GitHub. Go ahead and click Save, but now when you click the Knit button, instead of it saying Knit to HTML, it says Knit to md document, go ahead and click that button. This opens in a viewer window to preview, but it doesn't display the way it's going to really look in GitHub. So let's just close this viewer window for right now. So we're going to view the final GitHub markdown file when we upload it to GitHub in just a minute. And before we back everything up to GitHub, similar to what we did with the book down demo, let's create a docs folder in your module three project folder. We're going to create a new folder, and we'll call it docs. Let's put a copy of your HTML document in this directory. So let's make a copy, and we'll paste it into the docs directory. So before we back everything up to GitHub let's make one more change, we've got the HTML document shown here. I'm actually going to save this as a file in index.rnd and we'll click Save. Let's go ahead and Knit this to HTML, and we're going to take the index.html file, shown here in the file folder, and we're going to copy that and we're going to paste it into our docs directory. Now that we have everything in the docs directory, when we push everything to GitHub we're going to utilize the GitHub pages setting in the GitHub repository to serve our HTML document as a web page. So you'll notice here in the docs directory, we actually have two copies of this document. One is html document.html, and the other one is index.html, and I'm going to explain why we did this in just a moment. So let's go ahead and back everything up to your GitHub account. Open Git Bash, And make sure that you're in the Module 3 directory, and let's add all of our files. And we'll commit them, so add files for module 3. And then push everything up to the repository, finally we can type in git status to double check and nothing to commit and Working Tree is clean. So let's go back to the repository for module 3 and click refresh. You can now see all of your newly committed files. Let's next go to the Setting for your Module3 repository, scroll down to the section for GitHub Pages. And change the source here from None to master branch docs folder and click Save. So now that you've set the setting for source on your GitHub Pages to master branch docs folder, you'll notice that there's a link shown here for where your site is published. And it'll be something like username.github.io/module3. If you click on this URL, and open it in a new tab, at the moment it's saying site not found and that's okay. We know that one of the files that's in there is index.html. If we type this on the end of this URL and click Return, you can now see your HTML document served as a webpage. And you can link to other HTML documents simply by typing in the file name. For example, if I didn't have the index.html, I could have our original document, which is HTML document.html, and it'll also load this file. So you can use your docs directory to serve different webpages as needed. So congratulations, you've just made your first website with your HTML document. You might try viewing this new website on a mobile device like a cell phone, to get an idea of how this HTML documents display. The floating table of contents is especially useful on mobile devices.
