In NVE/Flood_forecasting: Title: A list a functions to support the Flomvarsling Shiny app
knitr::opts_chunk$set(echo = TRUE)
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 © 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:
-
The self_contained option is set FALSE; and
-
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
Site Navigation
The navbar element of _site.yml can be used to define a common navigation bar for your website. You can include internal and external links on the navigation bar as well as drop-down menus for sites with a large number of pages.
Here's a navigation bar definition that makes use of a variety of features:
_site.yml
name: "my-website"
navbar:
title: "My Website"
type: inverse
left:
- text: "Home"
icon: fa-home
href: index.html
- text: "About"
icon: fa-info
href: about.html
- text: "More"
icon: fa-gear
menu:
- text: "Heading 1"
- text: "Page A"
href: page_a.html
- text: "Page B"
href: page_b.html
- text: "---------"
- text: "Heading 2"
- text: "Page C"
href: page_c.html
- text: "Page D"
href: page_d.html
right:
- icon: fa-question fa-lg
href: https://example.com
This example demonstrates a number of capabilities of navigation bars:
-
You can use the type field to choose between the "default" and "inverse" navigation bar style (each theme includes distinct colors for "default" and "inverse" navigation bars).
-
You can align navigational items either to the left or to the right.
-
You can include menus on the navigation bar, and those menus can have separators (text: "--------------") and internal headings (text without a corresponding href).
-
You can include both internal and external links on the navigation bar.
-
You can use icons on the navigation bar. Icons from three different icon sets are available.
When referring to an icon you should use it's full name including the icon set prefix (e.g. "fa-github", "ion-social-twitter", "glyphicon-time", etc.).
HTML Navigation Bar {.toc-ignore}
If you want to have even more control over the appearance and behavior of the navigation bar you can define it in HTML rather than YAML. If you include a file named _navbar.html in your website directory it will be used as the navigation bar. Here's an example of navigation bar defined in HTML: https://github.com/rstudio/rmarkdown-website/blob/master/_navbar.html.
Full documentation on syntax of Bootstrap navigation bars can be found here: http://getbootstrap.com/components/#navbar.
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 {.toc-ignore}
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 {.toc-ignore}
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:
-
Files beginning with "." (hidden files).
-
Files beginning with "_"
-
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 {.toc-ignore}
R Markdown websites are can be hosted using GitHub Pages with two additions to the standard site configuration:
-
Add a file named .nojekyll to your site source code directory (this tells GitHub Pages to not process your site with the Jekyll engine).
-
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 {.toc-ignore}
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 {.toc-ignore}
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
NVE/Flood_forecasting documentation built on May 7, 2019, 6:04 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set(echo = TRUE)
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 © 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:
-
The
self_containedoption is setFALSE; and -
The
lib_diroption is set tosite_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
Site Navigation
The navbar element of _site.yml can be used to define a common navigation bar for your website. You can include internal and external links on the navigation bar as well as drop-down menus for sites with a large number of pages.
Here's a navigation bar definition that makes use of a variety of features:
_site.yml
name: "my-website" navbar: title: "My Website" type: inverse left: - text: "Home" icon: fa-home href: index.html - text: "About" icon: fa-info href: about.html - text: "More" icon: fa-gear menu: - text: "Heading 1" - text: "Page A" href: page_a.html - text: "Page B" href: page_b.html - text: "---------" - text: "Heading 2" - text: "Page C" href: page_c.html - text: "Page D" href: page_d.html right: - icon: fa-question fa-lg href: https://example.com
This example demonstrates a number of capabilities of navigation bars:
-
You can use the
typefield to choose between the "default" and "inverse" navigation bar style (each theme includes distinct colors for "default" and "inverse" navigation bars). -
You can align navigational items either to the
leftor to theright. -
You can include menus on the navigation bar, and those menus can have separators (
text: "--------------") and internal headings (textwithout a correspondinghref). -
You can include both internal and external links on the navigation bar.
-
You can use icons on the navigation bar. Icons from three different icon sets are available.
When referring to an icon you should use it's full name including the icon set prefix (e.g. "fa-github", "ion-social-twitter", "glyphicon-time", etc.).
HTML Navigation Bar {.toc-ignore}
If you want to have even more control over the appearance and behavior of the navigation bar you can define it in HTML rather than YAML. If you include a file named _navbar.html in your website directory it will be used as the navigation bar. Here's an example of navigation bar defined in HTML: https://github.com/rstudio/rmarkdown-website/blob/master/_navbar.html.
Full documentation on syntax of Bootstrap navigation bars can be found here: http://getbootstrap.com/components/#navbar.
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::kablefunction 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 {.toc-ignore}
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 {.toc-ignore}
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:
-
Files beginning with "." (hidden files).
-
Files beginning with "_"
-
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 {.toc-ignore}
R Markdown websites are can be hosted using GitHub Pages with two additions to the standard site configuration:
-
Add a file named
.nojekyllto your site source code directory (this tells GitHub Pages to not process your site with the Jekyll engine). -
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 {.toc-ignore}
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 {.toc-ignore}
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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.