7.13 Sharing HTML output on the web

One appealing aspect of rendering R Markdown to HTML files is that it is very easy to host these files on the Internet and share them just as one shares any other website. This section briefly summarizes numerous options for sharing the HTML documents that you have created.

7.13.1 R-specific services

RStudio offers a number of services for publishing various types of content created in R Markdown to the Internet. These services make it particularly easy to publish content by using the RStudio IDE or the rsconnect package (Allaire 2019).

  • RPubs enables free hosting of static single-file R Markdown content. It is easy to publish via the Publish button in the RStudio IDE or the rsconnect::rpubsUpload() function. Please see the “Getting Started” page (https://rpubs.com/about/getting-started) for more details.

  • ShinyApps.io allows for hosting dynamic content that requires a server to run R. For example, one can host interactive R Markdown documents that include Shiny components.12 ShinyApps.io is an analog to RPubs for Shiny applications. Apps and interactive R Markdown documents can be published using the push-button in the RStudio IDE or the rsconnect::deployApp() function. See the user guide (https://docs.rstudio.com/shinyapps.io/) for more details.

  • bookdown.org offers free hosting specifically for books written with the bookdown package. You may easily publish static output files of your book using the bookdown::publish_book() function.

  • RStudio Connect is an enterprise product that organizations may run on their own servers. It can host a wide variety of content created in R (such as R Markdown documents, Shiny apps, and APIs) in a secured environment with document-level access controls, viewership history, and more. Content can be published to RStudio Connect using manual upload, the rsconnect package, or with GIT-based deployment.

7.13.2 Static website services

In a few words, a simple static website is composed of any number of HTML files (typically containing an index.html, which is the homepage), JavaScript, CSS files, and additional content such as images. This collection of files can be hosted as-is on a web server and rendered in a web browser.

When R Markdown is rendered to the HTML output format, the result may be treated as a static website. Websites can range in complexity from a single, standalone HTML file (which is what we get when we use the default self_contained: true option), a set of files, or a sophisticated project like a website based on blogdown (which relies upon a static website generator). For more details, see Section 2.1 on Static Sites of the blogdown book (Xie, Hill, and Thomas 2017).

As a result, in addition to R-specific services, you may host your HTML document on many freely available static website hosting services. Commonly used options in the R community are:

  • GitHub Pages makes it particularly easy to publish Markdown and HTML content straight from a GitHub repository. You may specify whether to host content from either the main branch’s root, a docs/ directory on the main branch, or a specific gh-pages branch. Publishing new content can be as simple as pushing new HTML files to your repository via GIT.

  • GitLab Pages offers similar functionality to GitHub Pages for GitLab repositories. GitLab deploys content stores in the public/ directory of a repository. To build and publish content, you must provide a YAML file, .gitlab-ci.yml with instructions, but GitLab provides many helpful templates. For an example of hosting rendered HTML content, please see https://gitlab.com/pages/plain-html/-/tree/master.

  • Netlify is a platform to build and deploy static website content. It is a popular choice for web content created by the blogdown and pkgdown packages, but it can host all kinds of HTML files. There are many different publishing options including drag-and-drop, command line, or automated publishing from GitHub and GitLab repositories. Additionally, Netlify offers many helpful features such as website previews in pull requests. See the Netlify documentation (https://docs.netlify.com) or the RStudio webinar “Sharing on Short Notice” for more details.

References

Allaire, JJ. 2019. Rsconnect: Deployment Interface for r Markdown Documents and Shiny Applications. https://github.com/rstudio/rsconnect.
Xie, Yihui, Alison Presmanes Hill, and Amber Thomas. 2017. Blogdown: Creating Websites with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/blogdown.

  1. You may include Shiny components in an R Markdown document by setting the option runtime: shiny or runtime: shiny_prerendered in the YAML metadata. You will no longer be able to render your document to an HTML document as before; instead, you run your document with rmarkdown::run(). To learn more, please refer to Xie, Allaire, and Grolemund (2018) (Chapter 19: https://bookdown.org/yihui/rmarkdown/shiny-documents.html).↩︎