Overview

This is a direct copy of the rmarkdown documention website for learning purposes. Thomas Skaugen to provide a quick description of the DDD model.

Common Elements

Content

Typically when creating a website there are various common elements you want to include in all pages (e.g. output options, CSS styles, header and footer elements, etc.). Here’s some additions to the example above that makes use of common elements:

_site.yml

name: "my-website"
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

footer.html

<p>Copyright &copy; 2016 Skynet, Inc. All rights reserved.</p>

styles.css

blockquote {
  font-style: italic
}

Note that we’ve included an output element within our _site.yml file. This defines shared output options for all R Markdown documents within a site. Note that individual documents can also include their own output options, which will be merged with the common options at render time.

As part of our common output options we’ve specified an HTML footer (via the include: after-body: option) and CSS stylesheet. Note that you can also include HTML before the body or in the document <head>, see the documentation on includes for more details.

In addition to whatever common options you define, the are two output options which are automatically set when rendering a site:

  1. The self_contained option is set FALSE; and

  2. The lib_dir option is set to site_libs.

These options are set so that dependent files (e.g jQuery, Bootstrap, HTML widget libraries, etc.) are shared across all documents within the site rather than redundantly embedded within each document.

R Scripts

If you have R code that you’d like to share across multiple R Markdown documents within your site you can simply create an R script (e.g. “utils.R”) and then source it within your Rmd files. For example:

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

Rmd Partials

You may have common fragments of R Markdown that you want to share across pages within your site. To share Rmd fragments you should name them with a leading underscore (_) then include them within their parent Rmd document using the child chunk option. For example:

about.Rmd

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

More about this website.

```{r, child="_sessioninfo.Rmd"}
```

_sessioninfo.Rmd

Session information:

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

The leading underscore is an indicator to the site generation engine that the Rmd is a partial document to be included in other documents so it’s not Knit as a standalone document during site rendering.

The full source code for the above example can be found here: https://github.com/rstudio/rmarkdown-website-examples/tree/master/common-elements

HTML Generation

R Markdown includes many facilities for generation of HTML content from R objects, including:

  • The conversion to HTML of standard R output types (e.g. textual output, plots, etc.) within code chunks done automatically by knitr.

  • A variety of ways to generate HTML tables, including the knitr::kable function and the xtable package.

  • A large number of available HTML widgets that provide rich JavaScript data visualizations.

As a result, for many R Markdown websites you won’t need to worry about generating HTML output at all (since it’s created automatically).

htmltools Package

If the facilities described above don’t meet your requirements, you can also generate custom HTML from your R code using the htmltools package. The htmltools package enables you to write HTML using a convenient R based syntax (this is the same core HTML generation facility used by the shiny package).

Here’s an example of an R function that creates a Bootstrap thumbnail div:

library(htmltools)
thumbnail <- function(title, img, href, caption = TRUE) {
  div(class = "col-sm-4",
      a(class = "thumbnail", title = title, href = href,
        img(src = img),
        div(class = ifelse(caption, "caption", ""),
          ifelse(caption, title, "")
        )
      )
  )
}

You can write functions which build HTML like the one above then call them from other R code which combines them with your data to produce dynamic HTML. An R code chunk that makes use of this function might look like this:

Site Configuration

The _site.yml file has a number of options that affect site output including where it is written and what files are included and excluded from the site. Here’s an example that makes use of a few of these options:

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

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

The output_dir field indicates which directory to copy site content into (“_site" is the default if none is specified). Note that this can be “.” to keep all content within the root website directory alongside the source code.

Included Files

The include and exclude fields enable you to override the default behavior visa-vi what files are copied into the output directory. By default, all files within the website directory are copied into the output directory (e.g. “_site“) save for the following:

  1. Files beginning with “.” (hidden files).

  2. Files beginning with “_"

  3. Files known to contain R source code (e.g. “.R”, “.s”, “.Rmd”), R data (e.g. “.RData”, “.rds”), or configuration data (e.g. “.Rproj”, “rsconnect”)).

The include and exclude fields of _site.yml can be used to override this default behavior (wildcards can be used to specify groups of files to be included or excluded).

Note that include and exclude are not used to determine which Rmd files are rendered (all of them in the root directory save for those named with the _ prefix will be rendered).

Publishing Websites

R Markdown websites are static HTML sites that can be deployed to any standard web server. All site content (generated documents and supporting files) are copied into the _site directory so deployment is simply a matter of moving that directory to the appropriate directory of a web server.

This section provides additional documentation on publishing websites to several popular hosting services.

GitHub Pages

R Markdown websites are can be hosted using GitHub Pages with two additions to the standard site configuration:

  1. Add a file named .nojekyll to your site source code directory (this tells GitHub Pages to not process your site with the Jekyll engine).

  2. Change your output directory to “.” within _site.yml. For example:

    output_dir: "."

This keeps all of your output side-by-side with your source code in the root of your website (rather than writing it to the _site directory).

Note that when deploying to GitHub Pages using this configuration your source code, data, and everything else in your repository is all publicly available alongside your generated website content.

Alternatively, you can configure GitHub Pages to publish from a /docs subdirectory of your repository. If you work in this configuration you should change your output directory to “docs” within _site.yml. For example:

    output_dir: "docs"

You can find an example of a minimal R Markdown website configured for publishing to GitHub Pages here: https://github.com/rstudio/rmarkdown-website-examples/tree/master/gh-pages.

Amazon S3

If you have an Amazon Web Services account, you can deploy your R Markdown website directly to the S3 storage service. S3-based websites have global replication, support custom domains, and can be accelerated via the use of the Amazon CloudFront CDN.

For additional information on deploying websites to S3 see: http://docs.aws.amazon.com/gettingstarted/latest/swh/website-hosting-intro.html.

Other Web Hosts

There are a wide variety of options for static web hosting, all of which are compatible with R Markdown websites. This guide includes an overview of several of the more popular services: http://alignedleft.com/resources/cheap-web-hosting.

Additional Examples

Here are some additional examples of websites created with R Markdown:

Site Description Source
rmarkdown This website was created using R Markdown. There are a large number of pages (over 40) that are organized using sub-menus on the navigation bar. Disqus comments are included on each page via an after_body include. View code
flexdashboard Documentation for the flexdashboard R package. Illustrates using an R script to dynamically generate HTML thumbnails of flexdashboard examples from YAML. View code
bookdown Home page for the bookdown R package and publishing service. Illustrates creating a site with a completely custom theme (no use of Bootstrap). View code