A Basic Website in RMarkdown (with an R renderscript)

Just because it’s a basic website doesn’t mean it’s not an effective website. A process is discussed that helped me understand the building of a basic website in RMarkdown. Many of the basic ideas shown in this post (e.g. YAML spacing, using YAML scalar and array variables, R script for rendering, etc.) were also used in the building of this blog you are now reading.

Last Updated: Tuesday, July 05, 2022 - 16:24:05.

Caveat:LaTeX vs. RMarkdown

Over the years, I have developed a fair amount of experience with LaTeX (a typesetting language for mathematics) wherein a single .tex text file is essentially compiled to a single .pdf file as seen in Figure 1. I use this LaTeX example to illustrate and set expectations about what I was familiar with before coming to RMarkdown. Namely that (a) any packages required to compile to the .pdf are included in the .tex file (in the preamble) and all the text of the .pdf is included between the $$\backslash {\tt begin}$$ and $$\backslash {\tt end}$$ $${\tt document}$$. That’s all! At it’s simplest: one text file creates one output file. (b) White space between a $$\backslash {\tt begin}$$ and $$\backslash {\tt end}$$ does not generally, to my knowledge, affect the compiled output.

In contrast, it is my introductory experience with RMarkdown that many files (A) .Rmd (Rmarkdown), .yml (YAML), .css (Command Style Sheet) will need to play nice with each other to generate the desired .html webpage output and (B) white space, particularly in YAML, matters a lot! To be fair, this added complexity is to be expected as we are building a website in RMarkdown, which is quite a bit more complicated than creating a single .pdf file from LaTeX. Also to be fair, when learning any language, whether it be LaTeX or RMarkdown, there is syntax to get used to, error messages to decipher, and problems to solve.

Caveat:Sorry but I Have to Understand File Structure

In this post we illustrate via a minimal working example the files and organization, as seen in Figure 2, necessary for me to understand and build the basic website as seen in Figure 3.

A Basic Website Deconstructed

It helped me to think of a Basic RMarkdown Website as a piece of paper with a line drawn across the middle dividing the site into two main parts: A Top Navigation Bar (_site.yml) that handles the navigation to the sites content and a Bottom Body Section (index.Rmd) which is the sites landing page.

I must say at this point that the visual design of this Basic Website in RMarkdown is inspired by the blogs of Massimo Girondi and Gregory Gunderson which were written respectively in Hugo (with a theme based on hello-friend-ng based) and Jekyl with Liquid. Since I have only just started learning to use R, RMarkdown, Bookdown, and RStudio I thought it would be a good learning exercise to replicate some of the main features I liked from these sites using soley RMarkdown/Bookdown and YAML. This post was greatly improved from conversation with Matthew Hefner and Jill Reese (my wife extraordinaire). Not myself being a trained computer scientist or professional software developer, I learned from them the technical benefits of:

• The concept of using an R script to call render_site rather than using the Knit button (on each .Rmd file!).

• The general (best) practice of seperating .Rmd source files from .html output file. In this post we illustrate the use of RMarkdown render_site while in a future post we discuss Bookdown render_book.

• The use of scalar and array variables combined with cat.

Modifying the Site:Add to the Navbar

The Top Navigation Bar can be added to by editing the source file _site.yml. You can add more navbar items/pages via the “text-icon-href” sequence or you can make one of the navbar items into a drop down menu of pages via the “text-href” sequence.

Caveat:Spacing, Sp…aci..ng Matters A Lot

A pitfall I run into often with RMarkdown is getting the spacing correct in the _site.yml file (and YAML in general). This was particularly challenging when one finds code on the web and one wants to copy-and-paste as the pasting might not preserve the required indentation/tabbing. Without understanding why and how to use dashes, - and indentations I always felt like I was guessing at the YAML file format. That is unti I very fortunately ran across the _site.yml example:

Modifying the Site:Add to the Body

The Bottom Body can be added to by editing the source file index.Rmd. This file will become your index.html file (which is your website landing page). Change the image and add a little tagline or summary to make this uniquely your site.

Modifying the Site:Adding to the Icon Bar

The only really outside-the-norm part of our Basic RMarkdown Website is in the Icon Bar. To achieve this feature was an excellent exercise in learning to define and call array variables from the YAML header of the index.Rmd file using an R code block. The defining of array variables in the YAML header and getting them into our webpage via cat (concatenate) is a strategy that we use often when extending our Basic Website to an actual Blog. See a future post about the development of our Blog.

Building the Site via an R renderscript:Writing Necessary Files to a Single Output Folder

At this point you have:

1. added all your sites pages via the navbar in the file _site.yml

Your BasicWebsite-RMarkdown folder and file structure at this point might look something like that seen in Figure 12.

1. Final Step: You are now ready to run the R/RMarkdown renderscript seen in Figure 13 to create a single self contained output folder of .html’s for your basic website!

Getting to Go

If you have found this post interesting and wish to try something like it too, then you will likley need to bring a variety of tools together.

Having just recently acquired a new Mac, I took notes on all the system setup/installs that I needed to be able to build the above website and blog about it.

1. Installed (Homebrew) at Mac Terminal command line

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" • Note: Homebrew was installed on a machine with an Apple m1 chip in /opt/homebrew which is not on the default path of /usr/local/bin (found default from command line by echo$PATH). This needs to be resolved by pointing Mac to the brew install location by following the directions in (Homebrew Install Apple M1 Chip). Essentially we need to add Homebrew to our PATH by creating a ~/.zprofile (if not already present) and by adding the below to our ~/.zprofile

touch .zprofile

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)

brew doctor

1. Installed emacs from command line

brew install emacs

• Note: Checks that packages installed

brew list

• Note: Shows graphically how these packages are related

brew dips —tree —installed

1. Installed git and R via brew

brew install git

brew install R

• Note: Create (if not already present) and add below to ~/.zshrc file to enable git command complete at Mac Terminal command line

touch .zshrc

autoload -Uz compinit && compinit

1. Followed directions (ssh key-gen for git)

2. Installed (Rstudio IDE) with packages rmarkdown, bookdown, and font awesome