scripts_and_md.Rmd

---
title: "Example R Script and R Markdown files"
output: 
  html_document:
    fig_caption: no
    number_sections: no
    toc: yes
    toc_float: false
    collapsed: no
---

```{r set-options_all, echo=FALSE}
options(width = 105)
knitr::opts_chunk$set(dev='png', dpi=300, cache=TRUE)
pdf.options(useDingbats = TRUE)
klippy::klippy(position = c('top', 'right'))
```
# Introduction #

The `*.R` and `*.Rmd` scripts on this page illustrate a range of possible approaches for building a "project" `*.html` document. The examples range from a very simple R Markdown Notebook to a multi-page website. This page focues on the scripts and not the procedures for constructing a GitHub repository with a GitHub Pages web page, nor for serving web pages on `https://pages.uoregon.edu`/.

The examples can be replicated by copying the scripts, and creating the appropriate files in RStudio (e.g. as `alpha_plot_RScript.R` for this first example).

**Important:** When replicating Example 5 (a multi-page `*.html` document), the file `_site.yml` must be present in the R working directory. This file describes the "navbar" (navigation bar) and the layout of the page. If it is present, it will influence the other examples. So, for example, if `_site.yml` is present, it will try to add a navbar to the `*.html` file created by, say, Example 4, which has its own formating information this will produce unexpected results. To repeat, `_site.yml` *should* be in the working directory only for Example 5, and *should not* be in the working directory for the other examples.
(Note, instead of adding and deleting `_site.yml`, just rename it: `not_site.yml`.)

# Example 1 -- A simple R script #

- Script file: [[alpha_plot_RScript.R]](https://pjbartlein.github.io/REarthSysSci/Rmd/examples/alpha_plot_RScript.R)
- Output is text in the Console pane and graphics in the Plots pane.

This is an example of "bare" code that reads a netCDF file, does some setup, and plots a map. The output could conceivably be collected from the Console and Plot windows, and used to make an `*.html` file, but, that's what computers are for. This would involve:

- creating a `*.md` file, perhaps with VS Code, 
- copying text from the Console pane into it, 
- including saved images from the Plot pane (saving an image, say, as `alpha.png` and then including it in the Markdown file using the code fragment `![](alpha.png)`), and then finally 
- exporting the `*.md` file as an `*.html` file, or using Pandoc to render the `*.md` file. 

That would be tedious.

It would still be worth running the script, chunk-by-chunk, to get an idea of what the basic task of inputing data, setting up, and plotting is.

**Note: Copy everything in the boxes (except the first line if it's blank).**

````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/examples/alpha_plot_RScript.R"), collapse = "\n")`
````

[[Back to top]](scripts_and_md.html)

# Example 2 -- An RMarkdown Notebook file #

- Script file: [[alpha_plot_RNotebook.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/examples/alpha_plot_RNotebook.Rmd)
- Output is a single-page R Notebook `.html` file.

This R Notebook `*.Rmd` file produces the simplest of .html output. Note that it does not do any Markdown-type formatting, but simply embeds the output in the document. What makes this an R Notebook file (despite having the `*.Rmd` extension), is the presence of a "YAML" ("Yet Another Markup Language/YAML Ain't Markup Language") header that looks like the following:

````
---
title: "Example 2 -- An RMarkdown Notebook file "
output: html_document
---
````

This header specifies that the output of "kniting" the file should be an `*.html` file. Here's the code:

````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/examples/alpha_plot_RNotebook.Rmd"), collapse = "\n")`
````

[[Back to top]](scripts_and_md.html)

# Example 3 -- A single-page *.html file, with some styling

- Script file: [[alpha_plot_RMarkdown_1Page.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/examples/alpha_plot_RMarkdown_1Page.Rmd)
- Output is a single-page `*.html` file.

This example produces a single-page `.html` file as output, this time styled using the `html-md-01.css` stylesheet (the same one used for the course web page). The YAML header looks like

````
---
title: "Example 3 – A single-page *.html file, with some styling"
output:
  html_document:
    css: html-md-01.css
---
````

Here's the code:

````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/examples/alpha_plot_RMarkdown_1Page.Rmd"), collapse = "\n")`
````

[[Back to top]](scripts_and_md.html)

# Example 4 -- A single-page *.html file, with styling and navigation

- Script file: [[alpha_plot_RMarkdown.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/examples/alpha_plot_RMarkdown.Rmd)
- Output is a single-page `.html` file, with styling and some navigation.

The YAML header is more elaborate now, speciying a code syntax-highlighting scheme (`haddock`), and a output "Bootstrap" theme (`cerulean`) (See [[https://bookdown.org/yihui/rmarkdown/html-document.html#appearance-and-style]](https://bookdown.org/yihui/rmarkdown/html-document.html#appearance-and-style))

````

---
title:  Raster mapping
output:
  html_document:
    css: html-md-01.css
    fig_caption: yes
    highlight: haddock
    number_sections: yes
    theme: cerulean
    toc: yes
    toc_float: true
    collapsed: no
---
````

There is also a "code-chunk" that sets some `knitr` options.

Here's the code:

````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/examples/alpha_plot_RMarkdown.Rmd"), collapse = "\n")`
````

# Example 5 -- A multi-page web site #

**Important** To replicate this example, it would be best to creat an entirely new project in a differnt folder than the one you may have been working in.

- Script files:
  - [[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)
  - [[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)
  - [[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)
  - [[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)
  - [[README.md]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/README.md)
  - [[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
- Output is a multi-page website.

A multi-page R Markdown website, as the name suggests, includes a collection of `*.Rmd` files (that are each knit to create `*.html` files, plus a support file (`_site.yml`) that controls the navigation bar layout.  A sixth file is `README.md` file that appears on the main page of the GitHub repository. The steps below will create a minimalist multi-page web site.  The site will include an `index.html` page with a brief overview, a "Topics" tab with two pages, one an introduction, and the other being the "Raster mapping" page, and an "About" tab, implemented by four `*.Rmd` files (plus the `_site.yml` file).  Although R Studio contains great script-editing features, it's a little clunky as a text editor compared to Markdown-specific editors.  (In practice, if there is a lot of text to compose, edit, and format (as is the case with this page), it may be more efficient to do that in a Markdown editor, or VS Code, previewing while you go, and then include the contents of the `*.md` file created by the editor in a `*.Rmd` file using the Knitr "child document" chunk option (e.g. `{r child="index.md"}`)).  

Start by creating an R Markdown file that will produce a single-page `.html` file as output, which will be incorporated into the web site later:  

1. Create a new R Markdown file in the projects folder (File > New File > R Markdown);
2. Delete the sample code in the new page; 
2. Copy the contents of e.g. `index.Rmd`
1. Edit the paths in the script file as appropriate in `alpha_plot_RMarkdown_Site.Rmd`;
3. Knit the project to run the code and create the various `*.html` files.
4. Commit the changes, and push the website to the GitHub repository (explained elsewhere).

Here is the code:

[[index.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/index.Rmd)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/index.Rmd"), collapse = "\n")`
````

[[intro.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/intro.Rmd)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/intro.Rmd"), collapse = "\n")`
````
  
[[alpha_plot_RMarkdown_Site.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/alpha_plot_RMarkdown_Site.Rmd"), collapse = "\n")`
````

[[about.Rmd]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/about.Rmd)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/about.Rmd"), collapse = "\n")`
````

[[README.md]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/README.md)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/README.md"), collapse = "\n")`
````

[[_site.yml]](https://pjbartlein.github.io/REarthSysSci/Rmd/geog490/\_site.yml)
````
  `r paste(readLines("/Users/bartlein/Dropbox/DataVis/REarthSysSci/Rmd/geog490/_site.yml"), collapse = "\n")`
````

## The GitHub repository ##

The `knitr()` package is quite fussy about formatting of the `_site.yml` file so check it first in the case of later errors.

In RStudio, the "build tools" needed to create the web site will need to be configured.  On the RStudio menu, click on Build.  If there is a menu choice that says "Install Tools" do that first, otherwise click on "Configure Build Tools…"  A "Project Options" dialog will open.  On the "Project build tools:" dropdown box, select "Website"  The initial choices are probably fine, with the "Site directory" set to "(Project Root)" and the "Preview" and "Re-knit" checkboxes checked.  Upon clicking OK, a "Build" tab should appear in the upper-right pane.  If it doesn't, restart R Studio (Session > Restart R).  Select the build tab, and click on "Build Website".

At this point, the project folder should contain:	

```
/.git
/.Rproj.user
/docs
/alpha_plot_RMarkdown_Site_cache
/alpha_plot_RMarkdown_Site_files

html-md-01.css

.gitignore
.RData
.Rhistory

about.Rmd
index.Rmd
intro.Rmd
alpha_plot_RMarkdown_Site.Rmd

geog490.Rproj

README.md
_site.yml
```

… and the docs folder, 

```
/site_libs
/plot_alpha_RMarkdown_Site_files

html-md-01.css

about.html
index.html
intro.html
alpha_plot_RMarkdown_Site.html
README.html
```

The website should be viewable at:   [`https://pjbartlein.github.io/geog490/index.html`](https://pjbartlein.github.io/geog490/index.html) (the project's web page)

[[Back to top]](scripts_and_md.html)