Learning Objectives

  • Recognize the minimal requirements to build a website using R and Markdown.
  • Build three types of websites using R Studio, Github, Markdown and a sprinkle of Hugo
  • Publish these website to GitHub and/or Netlify

Introduction

Prerequisites

To full participate in today’s activites, you must have the following:

  • Version Control: A github account, git installed on your computer, the ability to push and pull from a local repository to a remote one, and the ability to connect git repositories to R through projects.
  • R & R Studio: with the following packages: knitr, blogdown v1.3, distill v1.2.4,
    • use blogdown to install Hugo by typing blogdown::install_hugo()
  • A Netlify account. I recommend that you sign up with your github account.
  • Set Intentions It’s easy to get lost in all the settings, tweaks, themes, customizations and so forth. Decide on some clear objectives to help keep you on track.

✏️Exercise 1: Set your intentions (Think-Pair-Share)

  1. Write down three things you want to accomplish with a website
  2. Get into random breakout rooms with another persons
  3. Share & discuss your goals


First watch, then do

We will be alternating a lot today where you watch me demo first, then you replicate on your own or in groups.

How you will actually learn this material:

Getting started: RMarkdown

R Markdown websites like this one can be built with a minimum of two files: a _site.yml and an index.Rmd.

The _site.yml file controls the overall structure of the website, such as the order of the navigation bar and the color theme.

When these files are rendered into HTML files, they can be hosted on GitHub for free. Then after turning on a few settings in your GitHub repository (repo) these files can be viewed as a magnificent webpage.

1. Create a public Github repo.

We are going to employ the “GitHub first, R Studio second” approach.

  • From your Repository page, click the green [NEW] button.
  • (Suggestion): Name this repo something like website_test_rmarkdown so you know it’s a playground.
  • keep it a PUBLIC repo
  • YES initialize with a README

Click ‘Create Repository’ to finish, but keep this page open. We’ll come back to it a few times.

2. Create a project in R Studio and clone your new repo into this project

  • Top right corner in R Studio click: New Project –> Checkout from version control –> Git
  • Go back to GitHub, and click on the green [Clone or Download] button.
    • Click the clipboard icon to copy the URL to your repo.
    • Paste this URL into the Repository URL box in R Studio.
      • (Strongly Suggested): Name this project the same as the repo name.
      • Subdirectory: Your path, your choice. Just don’t put a repo inside a repo.
  • Click Create Project

3. Create necessary files in R Studio

  • In the Terminal window (tab to the right of the Console), create the _site.yml and index.Rmd files using the touch command. Type the following commands in the Terminal one at a time, pressing Return or Enter after each line to execute.
touch _site.yml
touch index.rmd

You can view these files in the File pane (lower right). You can open supported file types by clicking on the name of the file from this pane. * Open both the _site.yml and index.Rmd files now.

✏️ Do steps 1-3. Put up a ✔️when you are done.

4. Configuring the _site.yml file

This is the file that controls your overall site’s configuration. If you are familiar with R Markdown files, this is the same type of ‘language’ that is used in the header area to control the document structure.

YAML headers, and this file, are very particular about spacing and tabs. To avoid unnecessary grief we are going to copy/paste code from the collaborative notes.

name: "my-website"
output_dir: "."
navbar:
  title: "My Website"
  left:
    - text: "Home"
      href: index.html
  • Give your website a name and title!

5. Configure your index page

This is your landing page. That is, the first page people see when they go to your website. You can add a title to this page using a YAML header as is shown in the bookdown website, or you can use a pound sign # as a first level header to make this title.

  • Create a title for your page using either a YAML header or a # sign. Using both is redundant.
  • Write a sentence or two welcoming your viewers to your website.

6. Building & previewing your website locally

Since we created the .yml file manually after creating the R Project, your project doesn’t quite know yet that it has a website to build.

  • Save your work and close down R studio.
  • Navigate to your repository folder on your computer, and open the project by double clicking on the R project file icon (a cube with the letter R).
    • Note: This is always how you should open your R Project files

There should now be a BUILD tab in the top right pane.

  • Click this tab, and then click the Build Website button.

An HTML file should now appear in your viewer pane.

  • Click the ‘Show in new window’ button to see your site in a full browser window.

  • Make a change to your index.Rmd, knit and refresh your browser window.

✏️ Do steps 4-6. Put up a ✔️when you are done.


Notes, Tips and Comments

  • ⚠️ Clicking “Build Website” will render every .md and .Rmd file in your top level project folder into an HTML file.
    • This is important to keep in mind when creating a website with a lot of pages.
    • Code files in sub-folders will not be automatically rendered.
  • You can re-render individual files by clicking ‘Knit’.
  • You can leave this browser window open as you work, refreshing the page to see new changes.

7. Push to GitHub & publish your website

Let’s get your test site up for the world to see.

  • In the Terminal window, stage and commit your files to version control by executing the following commands:
git add <file name>

This will stage all files that have been changed and/or added. Staging is the process of adding a file to be tracked under version control.

git commit -m "first commit"

Every commit needs a message. Try to make it informative, yet brief.

git push

This will push your changes up to GitHub’s servers online. You may have to enter your github username and password here. See happy git with R for help storing your github credentials.

  • Go back to your GitHub repo page and refresh - you should now see that your repo now contains the new code, and HTML files that you have been working on.
  • Click Settings in the top right of the navigation bar in your repository.
    • Scroll down to the Pages section in the left navigation pane.
    • Under Source, select main

After the page refreshes, you will see the URL to your website in at the top of GitHub pages section.

  • Click on this link to see what your public facing website looks like!
  • Copy this URL, we’re going to paste it in the repo settings so it can be found easy.
  • Go back to your main repo page by clicking on the name of your repo at the top of the GitHub page.
    • Click About on the right side panel
    • Paste the URL into the Website field.

8. Adding Content

Let’s add some content.

  • Create a new R Markdown file using File -> New R Markdown so we can get the example R Markdown content that includes a plot.
    • Save this file with a name such as project.Rmd
  • Add a link to the project HTML page to your _site.yml configuration file by adding a new text line to the navbar.
    - text: "My Projects"
      href: project.html

⚠️ Be mindful about the spacing. Make sure the - text: is directly in line with the home page item in the YAML header.

  • Rebuild your website by clicking the Build Website button in the Build tab in the top right pane.
  • View your changes locally, make a change if you see fit.
  • Add, commit, and push your changes.
  • Refresh your live webpage on GitHub to see the results!

👥 Do steps 7-8 in your breakout rooms. Come back to the main room when you are done.

Additional Features & References

  • Drill down navigation bar - indent in the YAML header under menu
  • Right alignment of some text
---
name: "my-website"
output_dir: "."
navbar:
  title: "My Website"
  left:
    - text: "Home"
      href: index.html
    - text: "Courses"
      menu:
      - text: "Math 1"
        href:  math1.html
      - text: "Math 2"
        href: math2.html
  right: 
    - text: "About"
      href: about.html
---

Level up: Blog Aware with Distill

Distill based websites are a nice enhancement to the Rmarkdown website. Very similar setup/structure, but with added ability to manage a blog. You can actually create static Websites with distill as well. Learn more about the difference here.

1. Create a new Github Repo and connect it to an R Project.

Follow steps 1 & 2 from the section above.

2. Use distill to turn the project into a website.

In the console, type the following:

library(distill)
create_blog(dir=".", title = "My Blog")

The basic scaffolding for a blog and an initial welcome post will be created within the root (.) sub-directory.

  • Shut down RStudio and re-open the project to enable the build tab. This is similar to step 6 above.

3. Configure the YAML header and build your site.

Open _site.yml Looks similar eh?

  • output: distill::distill_article instead of html_document
  • Change the description and name.
  • Change the output_dir: in the YAML to "docs"
  • Build your website by using the build tab and see if you can spot where these items show up.
    • You can also run render_site() in the console to build your site instead of using the build tab.

Changing the output directory

  • For this example we will be publishing through github pages, which doesn’t seem to recognize _site, but does docs.
  • This seems to be a github thing. Not a universal thing

What’s happening, is that all .md and .Rmd files in your root directory get knitted into .html files and placed into the docs folder. All content in the _posts folder also gets directly copied into the docs folder.

4. Create a post

Run the following code in the console:

create_post("Hello World", draft=TRUE)
  • Posts are created in the _posts subdirectory.
  • An entire subdirectory is created that reflects the creation date and name of post: 2021-06-15-hello-world
  • You can work on these posts individually, knitting as needed.
    • Files in a sub-directory do not get re-rendered when you build your site.
    • See this section of the distill documentation for how to rename posts and directories
  • When you are ready to make your post live, either fully remove or update the draft: true section in the YAML header

👥 In breakout rooms:

  1. Create new static page
  2. Add the new static page to the navigation bar
  3. Create a new post and write a few sentences about what you want to use this site for.
  4. Build your site and make sure you see all changes.

Come back to the main room when you are done.

5. Publishing your website

  • Add a .nojekyll file using either touch .nojekyll in the terminal, or file.create(".nojekyll") in the R console
    • Github pages tends to want to use the Jekyll website generator to compile pieces of a website into one cohesive site. You don’t need that in this case.
  • Add, commit, and push your changes to your github repository.
  • Activate github pages, and publish from the from the main branch and the /docs folder.

👥 RANDOM SHARE OUT:

  • You will be randomly assigned a new breakout room.
  • Each person take 1 minute, share their screen and show others what their page looks like.

Additional References

This was a basic introduction to these types of websites. See the documentation at https://rstudio.github.io/distill/blog.html to see how to:

  • create custom listings for subsets of posts
  • add categories to posts so they can be searched through
  • allow Disqus commenting and sharing of posts on social media
  • Themes
  • Publishing on sites other than github like Netlify
  • and more

Fancieness Level 1: Hello Hugo

The “simple” websites that were built above can be extended and enhanced well enough with some CSS and Rmarkdown wizardry. However, sometimes you may want a little more of a ‘modern’, ‘dynamic’ or ‘responsive’ feel, or to include a blog in your website.

This is when we enter the realm of [Hugo], - the self proclaimed “most popular open-source static site generator”.

Hugo is it’s own language, and for advanced usage of Hugo-based websites, some understanding of how Hugo works and reading those docs may be required. Alison Hill has a ton of resources on how to work with blogdown and Hugo, including a four part Summer of blogdown series of workshop notes. What we’re going to cover here is a very watered down, one hour(ish) version.

For now, we are just going to show you how to get started in this realm of fancy-ness using the R package blogdown. Then you can go break it later. The super official blogdown documentation is linked in the References section at the bottom of this page.

If you did not do so beforehand, install the blogdown package, and use it to install Hugo using blogdown::install_hugo().

1. Create a new Github Repo and connect it to an R Project

You got this. Fifteenth time is the charm.

2. Create a new site with a specified theme

The blogdown package will setup the necessary files, folder structures and theme files from a pre-specified them that is available on github. The example we will start with is a very simple site containing a few pages and a blog.

blogdown::new_site(theme='yihui/hugo-lithium')
  • This could take up to a minute to download all necessary files.
  • Want to serve and preview the site now? (y/n) n (say no)
  • “Serve” your site by doing one of two things:
    • In the console type: blogdown:::serve_site()
    • In R studio, go to the Addins drop down menu, and select “Serve Site”

This is the “website compilation” part. R/Markdown are turning all the .md and .Rmd files into HTML, Hugo is linking them together under the direction of themes and the config file.

❓ Poke around on this site. What do you notice?

3. Explore configuration files

Let’s start by looking at the files that are contained in the root folder of this project.

  • index.Rmd: Nothing really is there!
    • This is one of the primary differences between this type of site building and the one we just finished.
    • Content is handled in a very different manner.
  • config.yaml: Functions similar to the _site.yml file, with a LOT more options.
    • we will not go into detail about these parameters, because they are theme specific.

✏️ Customize your site

  • Remove the twitter link
  • Change the GitHub link to point to your GitHub account
  • Give your site a different title.
  • Save


❓ Were you able to see the results of each of the changes you made on the live site? This is the magic of ✨Live Reload ✨.

4. Explore and modify static content files.

  • Open the content folder. Right now there is only an about.md file. * Opening this file we see a familiar YAML header, and a body of text.
  • This folder is where we can add more static pages, such as a CV.
    • Since we are not using any R code in this specific document, we can stick with the simpler markdown only (.md) file format.

✏️ Update content

  • Change the title and content of the about.md.
  • Copy the about.md file, rename this as cv.md.
    • You can do this in R Studio by clicking the box to the left of the file name in the Files window, then clicking More –> Copy
  • Change the title, add a few bullet points and save.
  • Go back to the config.yaml file, and add a new menu item
  • Save this file, notice changes.

5. Blog posts

On your newly updated website, clicking on the icon in the top left. This will take you back to the landing page. For this theme, the landing page is a blog (instead of a static page such as About). Clicking on one of these posts takes you to the page that contains the post itself.

The content files for posts are stored under content/post/ folder. If you look there now you’ll see some markdown (.md), some R Markdown (.Rmd) files, and their associated .html output files.

Creating new posts

  • Option 1: Copy/paste/modify one of the example files already in this folder.
  • Option 2: Use the R Studio Addins to setup the page structure for you.
    • This is the one we’re going to use
    • Using the UI allows you to easily set catgories, tags and the like.

✏️ Add a post

  • Click Addins –> New Post
    • This may require you to install and/or update new packages. Go ahead and do so.
    • If you run into seemingly endless package installation loops, restart RStudio and re-try.
  • Give your post a title, author name, a category and a tag.
    • Categories and tags are optional, but for this example go ahead and set them.
  • Select the .Rmd format for this example. What this .Rmarkdown? 🤷. See this github issue as a place to start to learn about how these two extensions work with hugo.
  • Select Done
  • Add some simple content for display such as
    • A header
    • a plot
    • a sentence
  • Save let live reload do it’s magic. If it doesn’t work, you can always knit to see it work.

6. Serve Site

  • When we started the new site in step 2, we also ran serve_site() to see the live preview.
  • At a later point when you want to come back to working on your website, opening the project file itself will not initiate a serve_site(). You will have to do this manually.

7. Push to GitHub

Go ahead and save your work, add, commit, and push your content to your github account.

8. Publish your website

If you have your own server, and you are familiar with website deployment then you can roll your own as you are used to. For those of us that have absolutely no idea how to host a website, a very good option that is very user friendly (and free) is Netlify.

You could use GitHub Pages as we did previously to host a Hugo based website, but there are some tweaks that you have to do to get GitHub to work with/around Jekyll in the way Blogdown/Hugo builds the sites. If you want to learn more about the why’s, go read the docs at https://bookdown.org/yihui/blogdown/deployment.html

✏️ Publish

  1. Sign in to Netlify using your github account.
  2. Select New site from Git -> continuous deployment: github
  3. Choose your hugo website repo
  4. Leave all defaults, and click ‘deploy’
  5. When it’s done it will give you a URL that you should customize.
    • Site settings -> Change site name

Almost done! We need to do one more big of configuration on the Rstudio side so that when you push change to github, it will trigger a redeploy automatically.

✏️ Update deployment settings

Go back to your config.yml file and change the baseurl to your website URL.

Now you are GTG! At least at a starting page. The devil is always in the details (of the theme). That’s where we’re going next.

  • ⚠️ Hugo has a TON of themes: https://themes.gohugo.io/ . Not all work with blogdown, and not all are easy to work with. Here is a blog post by Peter Baumgartner on important thoughts on choosing a theme to work with.
  • The lithium theme has a very simple YAML configuration file. Each theme is different and unique. Reading the documentation (generally contained in the readme) is critical.

Fancieness Level 5000: Hello Academic Theme.

We do not have time to go through this in detail. PLEASE follow up with Alison Hill’s Up and running with blogdown in 2021 post before you start serious webpage building. She’ll set you up with all the proper checks. We’re just fiddling around here and getting you introduced.

1. Create a new Github Repo and connect it to an R Project

2. Create a new site with the Academic theme

blogdown::new_site(theme = "wowchemy/starter-academic")
  • This time let blogdown start the server for us.
  • Expand your site out of the viewer pane and into a browser window.
  • Scroll down and be overwhelmed by ALL the parts.

3. Simplify!

  • Each one of those horizontal panes is controlled with a widget.
  • Massive cognitive overload to have all of them on.
  • Start your configuration in the content/home folder.
    • each one of these .md files are a widget.

✏️ Control your widgets

  • Open hero.md
  • Add active: false to line 3 (under widget: name)
    • This will add the parameter active, and set it to false. I didn’t make up that name, I found the solution here.
  • Save this file, and look back at the page in the browser. Which section was deleted?
  • Turn off demo.md the same way. This one already had a spot for the active parameter.

4. Personalize

  • People are controlled under content/authors. You specifically are in /admin/_index.md, and AFAIK you are not Nelson Bighetti.

✏️ Make it about you Change each of these one at a time, watching the live reload to make sure you know what they are linked to.

  • bio
  • interests
  • title
  • organization
  • role
  • paragraph at the bottom

5. General layout for projects, publications, events

  • Each has a folder under /content with an _index.md file
    • This index file controls the look of the widget, how many items to show, if there is an image or caption etc.
  • Each item (individual project, course) has their own folder
  • Each item is controlled by an index.md
    • So to add new projects, publications etc, add a new folder, copy an index.md from another project, and modify.
    • Cover images are always named featured
    • The specific configuration for a project is different from a publication, is different from an event. So if you’re making new events, make sure you copy the files from another event.

6. New blog posts

  • Use the new post addin in R Studio
    • This creates a new folder similar to what was seen before, with the folder name containing the date and slug.
  • Note it gives you the option to put this post in other subdirectories. Stick with posts until you’re more familiar with blogdown.
    • The post template that is created isn’t driven by the folder. I.e. if you create a new post and select the “project” folder, it will still give you a post template for a new blog post, not a project.

Random other tidbits

  • Some widgets are useful, just not on the home page. Widgets can be transplanted to other pages.
  • Check the content/home/widget.md for customization options
  • navbar items are controlled in config/_default/menus.yaml
  • updating your theme can be painful…

Additional References

In recommended order