Skip to content

Instantly share code, notes, and snippets.

@chrisdaaz

chrisdaaz/rmarkdown-tutorial.md

Last active April 29, 2023 20:55
Show Gist options
  • Save chrisdaaz/1ba8cf670802f7395e43466e4f347672 to your computer and use it in GitHub Desktop.
Save chrisdaaz/1ba8cf670802f7395e43466e4f347672 to your computer and use it in GitHub Desktop.
Download ZIP
Writing and Publishing with R Markdown
Raw
rmarkdown-tutorial.md

This gist was created for the R User Group at Northwestern University.

Overview

R Markdown is an open source R package that adds R programming features to Markdown, a simple, plain-text syntax and file format. R Markdown is the basis for tools like Bookdown and Blogdown, which are static site generators that convert R Markdown files into HTML, PDF, and Word documents for educational, technical, or scholarly uses. We’ll cover the basics of using these packages, install them in an RStudio environment, and discuss free deployment options publishing documents to the web.

Contact for consultations or assistance with any static site publishing projects: chris-diaz@northwestern.edu

Presentation slides

R Markdown

Here's the definitive guide to R Markdown Here's a collection of R Markdown examples

Installation

  • Open R Studio
  • Create a New Project
  • Assign the project a directory name and folder
  • Check the box for "Create a git repository" (optional; good for version control and saving to GitHub or GitLab)
  • In the console, run install.packages("rmarkdown")

Create a file

  • In R Studio, click on File -> New File -> R Markdown...
  • Enter in a Title and Author for the file
  • Select HTML as the default output format
  • You have options to create a Document, Presentation, or Shiny application
  • Once you close the dialog box, you will see a new file open with sample content and the YAML front-matter you specified
  • Save the file in your current directory (File -> Save As... -> first-rmarkdown.Rmd)

Test R Markdown features

  • To see R Markdown in action, click on the -> Run button at the top of the document panel. This will run the sample R code chunks inline, allowing you to see a table and a plot. Feel free to swap out the sample data with any other data you have.
  • To render the file as an HTML webpage, click on the Knit button at the top of the document. This will open a new R Studio window that displays the formatted HTML document. You can also click on Open in Browser to see how your specific web browser displays the document. Note: If you run into an error, you might need to edit the output section of the YAML front-matter:
output: 
  html_document:
    self_contained: no
  • To render the document as a Word Doc, click on the drop-down arrow next to the Knit button and select Knit to Word. You can also change the output line in the front-matter to output: word_document (see above if you encounter any errors). Note that this creates and saves a Word document to your project directory.
  • To render the document as a PDF, click on the drop-down arrow next to the Knit button and select Knit to PDF. You can also change the output line in the front-matter to output: pdf_document (see above if you encounter any errors). Note that this creates and saves a PDF document to your project directory.

Blogdown

Here's the blogdown reference book

Installation

  • Open R Studio
  • Create a New Project
  • Assign the project a directory name and folder
  • Check the box for "Create a git repository" (optional; good for version control and saving to GitHub or GitLab)
  • In the console, run install.packages("blogdown")
  • Also install Hugo, the static site generator blogdown is based on: blogdown::install_hugo()

Quick Website Example

  • In the console, run blogdown::new_site(). This will create a template directory for your site, start an internal web server, and open a preview of the website in R Studio's viewer.
  • Click on the "Hello R Markdown" post in the viewer. This should also be the open 2015-07-23-r-markdown.Rmd file in the R Studio text editor.
  • Make some edits to 2015-07-23-r-markdown.Rmd in the text editor and save them to the file. Any edits you make should also reload in your viewer so you can see how your edits get rendered by blogdown.

Change to a New Theme It is recommended that you select a Hugo theme before your create your blogdown project. Because Hugo is a new software under active development, you will have better luck with themes that have been updated within the past year. You can browse a list of published themes here: https://themes.gohugo.io/

  • If you are starting from a clean project directory with blogdown and hugo installed, you can create a new site with your theme of choice by running blogdown::new_site() and passing an argument that specifies the theme from GitHub using this syntax: theme = "[GitHub Username]/[Theme repository name]". Example: blogdown::new_site(theme = "gcushen/hugo-academic").
  • If have a website already but need a new theme, it is easier to start a new project with the new theme than it is to install a new theme in an existing project because of the way Hugo configurations work. Luckily, it is easy to migrate to new project directories because all you need to do is copy your content/ folder to the new project. Some themes have idiosyncratic ways of organizing and building content so it is always recommended you consult with the theme's documentation.

Deploy your website Consult the reference book for instructions on deploying your website to a free or cheap hosting provider.

Bookdown

We don't have enough time to discuss the bookdown package, but it works in much the same way as blogdown; however it is optimized for online and printer-friendly e-books. The blogdown reference book is itself a bookdown example. Full documentation is available here.

Credits

This gist is based on the wonderful documenation available from R Studio and Yihui Xie.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment