Background

Writing documents in R Markdown is relatively straightforward once you know some of the basics. You can create many different formats, including .pdf, .html, and .doc, and customize them in a variety of ways.

Templates

There are a number of existing templates available in the rticles package that you can use for knitting your document to a specific style in .pdf format. For .html formats, there are a variety of “themes” available as well. For example, this document was created with the spacelab theme.

Task: Open RStudio and from the menu options select File > New File > R Markdown…

Tip: You can change the Title, Author, and Date, fields here, but we’ll do that later.


Task: Leave the Default Output Format as HTML and click on OK.

Success: You now have a new .Rmd file ready for editing, which includes some placeholder text and code blocks.


Document layout

Front Matter (YAML)

Every Markdown document begins with a section of plain text written in YAML (“YAML Ain’t Markup Language”). This block of human readable code is used to define some of the document’s metadata such as the title, author, and date. It is also used to specify the document’s format (eg, HTML or pdf) and its layout (eg, theme, font).

Tip: The front matter is defined in a block of text that begins and ends with 3 dashes ---.

Here is the YAML for our new simple HTML document:

---
title: "Untitled"
author: "Mark Scheuerell"
date: "10 February 2023"
output: html_document
---

The YAML can include a lot more information as well, including fields for various pre-defined themes, a table of contents, adding citations and formatting references, and whether to use other files as formatting templates. For example, here is the YAML for this document with today’s class notes:

---
title: "Using R Markdown for publications"
subtitle: "Part 1"
date: "10 February 2023"
output:
  html_document:
    theme: spacelab
    highlight: textmate
    css: ["lecture_inst.css", "fontawesome.css", "solid.css"]
    toc: true
    toc_float: true
    toc_depth: 3
bibliography: "references.bib"
csl: "ecology.csl"
---

Knitting your file

The process of creating a nicely formatted document (e.g., html, .pdf) from the raw markdown code in the .Rmd file is known as knitting. You can knit a .Rmd file from the R command line, but the easiest way in RStudio is to simply click the Knit button at the top of the editing pane.

Tip: Clicking on the downarrow to the right of the Knit button brings up some additional options.


Task: Click on the Knit button to render your .Rmd file as a .html file.

Note: Knitting a .Rmd file automatically saves it. The first time you click Knit, you will be prompted for the filename and location where you want to save the file.

Success: You now have a knitted .html file.

Make some changes

Let’s make some changes to our markdown document and knit them.

Task: Add a title, subtitle, and table of contents (toc) to the YAML.

Note: The indentation and colons in the YAML subfields are necessary.

---
title: "Creating online reports"
subtitle: "A markdown demonstration"
author: "Mark Scheuerell"
date: "10 February 2023"
output:
  html_document:
    toc: true
    toc_float: true
    toc_depth: 3
---

Task: Add a level-1 and level-3 header to your document.


Task: Click the Knit button to see you changes.


Tip: The table of contents will change as you scroll down through the sections and float along the left side.

Publishing reports online

Now that we’ve seen how to create an HTML report using R Markdown, let’s publish a report online so that it can be shared with and viewed by others.

Create a new repo

Task: Navigate to GitHub and create a new public repo called markdown-demo. Add a README.md file and an R .gitignore file as well (you can skip a license file). CLick the green Create repository button when you’re ready.

Task: Click on the Settings button in the upper right.

Task: Click on the Pages button on the left side.

Task: Click on the None button under the Branch heading and swith it to main.

Task: Click on the / (root) button under the Branch heading and swith it to /docs.

Task: When you’re ready, click on the Save button.

Success: Your repo is now set to use GitHub Pages for displaying HTML files.

Create an RStudio project

Task: Create a new project in RStudio from the markdown-demo repo you just created.

Task: Open a new R Markdown document and give it a title. Select the HTML format and click OK when you’re done.

Task: Save your new document in a new subfolder within your markdown-demo project called docs with the filename index.Rmd.

Tip: When you click Save, your markdown document will be knit automatically.

Note: You should now see a /docs folder in the RStudio file pane. Click on it and you will see your index.Rmd and index.html files there.

Task: Commit your changes to the index.Rmd and index.html files.

Task: Push your commit when done.

Viewing your document

Now that we’ve pushed our basic HTML report to GitHub, we should be able to view it online.

Task: Navigate back your markdown-demo repo on GitHub and you’ll see the /docs folder containing the index.Rmd and index.html files you just pushed.

Note: If you click on the index.html file, you’ll notice that it just displays the raw HTML code rather than a nicely formatted website.

Tip: GitHub cannot render HTML files in a normal repo, but you can view your new document by navigating to https://USERNAME.github.io/markdown-demo/ where USERNAME is your GitHub username.

Success: You now have an online report that you can update by making changes in your RStudio project and pushing them to GitHub.

Tip: You can add a link to your newly rendered document by edited the main page of your repo.

Task: Click on the small gear icon in the upper right, which will bring up a window to edit some aspects of your repo.

Task: In the Website field, type or copy/paste the link to your rendered site, which should be https://USERNAME.github.io/markdown-demo/ where USERNAME is your GitHub username. Click on the green Save changes button when you’re done.

Success: Your repo has now been updated to include a direct link to your properly rendered HTML report.

Endnote

Now that you have seen how to create HTML reports and display them online, you’re ready to add more details such as equations, code blocks, figures, tables, etc.

Tip: You can refer to this primer for some additional information on formatting R Markdown documents.