R Markdown websites: https://rmarkdown.rstudio.com/lesson-13.html
R Markdown book: https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html
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
website
_site.yml
, index.Rmd
and
about.Rmd
_site
folder createdoutput_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
website
_site.yml
, index.Rmd
and
about.Rmd
_site.yml
, specify
output_dir: "docs"
docs
folder createdAn 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.
_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>
_site.yml
, set output_dir: "docs"
.
Build the website and inspect folder docs
_site.yml
so it includes output
optionsfooter.html
and include it in the website
with after_body: footer.html
index.Rmd
The index.Rmd
file is the home page of the website.
---
title: "My Website"
---
This is an R Markdown website
.Rmd
filesAdditional individual .Rmd
files are used to add more
pages to the website.
---
title: "About This Website"
---
More about this website.
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"]
).
Rmd
partialsWhen 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()
```
.Rmd
files, source an R script and include a
child .Rmd
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.
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)
```