2 R Markdown websites

In this tutorial we show how to create a website using a collection of R Markdown documents. An example of R Markdown website is http://rspatialdata.github.io/.

Briefly, to create an R Markdown website, we need the create the following files and put them in a directory:

A file named _site.yml which contains the layout, theme and other options of the website.

name: "my-website"
navbar:
  title: "My Website"
  left:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html

A file named index.Rmd with the content of the home page of the website.

---
title: "My Website"
---

Hello, Website!

A collection of individual .Rmd files with content of the pages of the website. For example, about.Rmd.

---
title: "About This Website"
---

More about this website.

Then, to deploy the website, we need to execute the rmarkdown::render_site() function from within the directory containing the files. Alternatively, if we have created an RStudio project for the directory, we can click the Build button in RStudio which calls rmarkdown::render_site(). Then HTML files will be created in a directory called _site (by default) and this directory can be deployed as a standalone static website to any standard web server.

The following sections and the R Markdown book provide more information about the creation of R Markdown websites.

Create an R Markdown website

  • Create an RStudio project in a directory called website
  • Create files _site.yml, index.Rmd and about.Rmd
  • Deploy the website with the Build button in RStudio
  • Inspect the _site folder created

2.1 output_dir

In _site.yml, the output_dir field indicates the directory to copy site content into when rmarkdown::render_site() is executed. By default this directory is _site. If we wish to publish the website in GitHub Pages we need to change it to the root or the docs subdirectory as follows:

output_dir: "."     # root of master branch
output_dir: "docs"  # docs directory of master branch

_site.yml

name: "my-website"
output_dir: "docs"
navbar:
  title: "My Website"
  left:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html

Create an R Markdown website

  • Create an RStudio project in a directory called website
  • Create files _site.yml, index.Rmd and about.Rmd
  • In _site.yml, specify output_dir: "docs"
  • Deploy the website with the Build button in RStudio
  • Inspect the docs folder created
  • Share the website online in GitHub Pages

3 R Markdown website files

An R Markdown website can be created with a directory that contains files _site.yml with the layout, theme and other options of the website, index.Rmd with the home page, and a collection of individual .Rmd files with additional content.

3.1 File _site.yml

The _site.yml file provides the global YAML header for the website. This file specifies the layout, theme and other options of the website.

_site.yml

name: "my-website"
output_dir: "docs"
navbar:
  title: "My Website"
  left:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
output:
  html_document:
    theme: cosmo
    highlight: textmate
    include:
      after_body: footer.html
    css: styles.css

The name field provides a suggested URL path for the website when it is published (by default this is just the name of the directory containing the site).

The output_dir field indicates the directory to copy site content into when rmarkdown::render_site() is executed. The default directory is _site. We can change it to the root (".") or the docs subdirectory ("docs") if we wish to publish the website in GitHub Pages.

The navbar element defines the navigation bar for the website.

The output element defines shared output options for all R Markdown documents in the website. Individual documents can also include their own output options, which will be merged with the common options when the website is rendered. Here we describe some of the output options. More information can be seen at the R Markdown book.

theme specifies the Bootstrap theme for the website page. Themes are drawn from the Bootswatch theme library.

highlight specifies the syntax highlighting style. Supported styles include default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, and textmate.

The css option can be used to add our own CSS. If we want to provide all of the styles for the website from our own CSS (e.g., styles.css) we need to set theme: null and highlight: null.

styles.css

blockquote {
  font-style: italic
}

We can specify a footer by using the option include: after-body:

footer.html

<p>Copyright; 2020 GeoHealth. All rights reserved.</p>

  • In _site.yml , set output_dir: "docs". Build the website and inspect folder docs
  • Modify _site.yml so it includes output options
  • Create file footer.html and include it in the website with after_body: footer.html

3.2 File index.Rmd

The index.Rmd file is the home page of the website.

---
title: "My Website"
---

This is an R Markdown website

3.3 Individual .Rmd files

Additional individual .Rmd files are used to add more pages to the website.

---
title: "About This Website"
---

More about this website.

5 Include and exclude files

name: "my-website"
output_dir: "_site"
include: ["import.R"]
exclude: ["docs.txt", "*.csv"]

The include and exclude fields enable to override the default behavior about what files are copied into the output directory. By default, all files within the website directory are copied into the output directory except files beginning with _ and . (hidden files), and files known to contain R source code (e.g., *.R, *.Rmd), R data (e.g., *.RData, *.rds), or configuration data (e.g., *.Rproj).

We can also exclude a whole folder by specifying the name of the folder (e.g., exclude: ["folder"]).

5.1 R scripts and Rmd partials

When writing index.Rmd and the individual .Rmd files, we can use R scripts and Rmd partials.

For example, if we have R code we want to share across multiple R Markdown documents, we can create an R script and source it within the .Rmd files.

```{r}
source("utils.R")
```

Also, if we have R Markdown documents that we want to share across several pages in the website, we can include them in the parent .Rmd document using the child chunk option. Note that the child .Rmd files need to be named with a leading _ so they are not compiled as standalone documents during the site rendering.

about.Rmd

---
title: "About This Website"
---

More about this website.

```{r, child = "_session-info.Rmd"}
```

_session-info.Rmd

Session information:

```{r}
sessionInfo()
```

  • In the .Rmd files, source an R script and include a child .Rmd

6 Rendering the website

While we are developing our website, we can render individual pages of the website using the Knit button of RStudio. Knitting an individual page will only render and preview that page, not the other pages in the website.

To render all pages in the website, we can execute rmarkdown::render_site() or click the Build button in RStudio which calls rmarkdown::render_site(). When we do this, all the .Rmd files in the directory (except files beginning with _) are rendered into HTML files. The generated HTML files and any supporting files such as CSS files are copied into the directory _site (by default) or the directory specified in output_dir: and are ready to deploy as a standalone static website.

6.1 Knitr caching

During development of the site, if the website takes a long time to render, we can enable the caching to be able to preview it faster. We can do this by adding the cache = TRUE to an individual chunk.

```{r, cache = TRUE}
data <- longComputation()
```

Or we can add cache = TRUE to the global chunk option defaults to enable caching for an entire document.

```{r setup, include = FALSE}
knitr::opts_chunk$set(cache = TRUE)
```

  • Share the website online in GitHub Pages