Use of this document

This is a study note for using $rmarkdown $ package to generate rmarkown’s site. For more details on the study material see: (https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html)

supplemental materials:

Note: some code chunk in this document include syntax for code chunk, I mask the syntax by a backslash to avoid the issue of rendering this document, so ignore the \ in those code chunk.

1 Workflow

the rmarkdown package had provided a simple site generator

1.1 Elements

There is a list of Common elements need to be created manually:

elements Description
_site.yml (required) configuration file. Editable for navigation bar. Connect all fileS includinG footer.html, styles.css and all *.Rmd therefore the resulting *.html,
index.Rmd (required) first Rmd files, usually become the Homepage of the website
about.Rmd additioanal information for the website
footer.html footer
styles.css text style

1.2 Build

  • Preview Current: Click Knit button or rmarkdown::render_site("about.Rmd") to render and preview the current page of the individual .Rmd file
  • Preview All: Run rmarkdown::render_site() on Rstudio Console command line, the following will occur
    • rendered all *.Rmd and *.md into HTML, but not _*.Rmd at the current working directory,
    • generated HTML files and any supporting files (e.g., CSS and JavaScript) are copied into an output directory (_site by default)
  • however, that Markdown files beginning with _ are not rendered. This is a convention to designate files that are to be included by top level Rmd documents as child documents

1.3 Clean

To clean up all files generated by rendering your site's Markdown documents, including knitr's *_cache directories:

rmarkdown::clean_site(preview = TRUE): list which files will be removed rmarkdown::clean_site(): actually remove the files

1.4 knitr caching

If your website is time consuming to render, you may want to enable knitr's caching during the development of the site, so that you can more rapidly preview.

  • To enable caching for an individual chunk, add the cache = TRUE chunk option to enable caching for an individual chunk {r, cache = TRUE}
  • To enable caching for an entire document, add cache = TRUE in knitr::opts_chunk$set() in the {r setup} chunk.

2. Common elements

2.1 Site Structure and Style

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

2.1.1 _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

It can can be used to define a advance navigation bar for your website

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

2.1.2 footer.html

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

2.1.3 styles.css

blockquote {
  font-style: italic
}

2.2 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 (_), and then include them within their parent Rmd document using the child chunk option. For example:

2.2.1 about.Rmd

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

More about this website.

2.2.2 _session-info.Rmd

may add some program to add seesioninfo

Session information:
  
\```{r}
sessionInfo()
\```

2.3 R scripts

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

---
title: "sourcing utils.R"
---

source("utils.R")

3. Graphic

This section introduce how to insert graphs or figures from local and online to .Rmd.

3.1 Local Image

Add a R chunk to run the following to insert a local image.

\```{r, echo=FALSE, fig.cap="A caption", out.width = '100%'}
\knitr::include_graphics("temp.png")
\```

3.1 Online Image

Or using a online image by doing the following.

<center>
![A caption](https://www.95visual.com/sites/default/files/images/inline/file_format_chart.png){
width=20% }
</center>

4. Output

4.1 Format

4.1.1 .HTML with table

---
title: "Note-rmarkdowns site generator"
author: "Weiquan Luo"
date: "2021-12-03"
output:
  html_document:
    toc: true
    theme: united
---

4.1.2 Github .md

---
title: "ggplot2 Extension for Fun"
author: "Weiquan Luo"
date: "2021-12-03"
output: rmarkdown::github_document
always_allow_html: yes
---

4.2 .R with Code only

knitr::purl("file.Rmd")