Who am I?

Resul Umit

• post-doctoral researcher at the University of Oslo

• teaching and studying representation, elections, and parliaments

  • a recent publication: Parliamentary communication allowances do not increase electoral turnout or incumbents’ vote share

• teaching workshops, also on

  • writing reproducible research papers
  • version control and collaboration
  • working with Twitter data
  • automated web scraping

• more information available at resulumit.com

My First Website

Using WordPress

• opened just before starting my PhD in 2013, at wordpress.com

• at first, with rare updates

  • none based on data
  • required getting used to at every login
    • a system that I used only for my website

• then, with more frequent blogposts

  • frustrations with posts based on data
    • slow to write and edit
      
      
  • still required getting used to at every login

My Current Website

Using R

• migrated from WordPress in 2018

• frustrations with blogposts based on data

  • slow to write and edit
  • blogdown (Xie et al., 2021a) makes quantitative academic writing efficient

• required getting used to at every login

  • a system used only for website updates
  • a system that I use everyday for other tasks
    • cleaning and analysing data, writing results for publication

The Workshop — Overview

• One full day, on how to create websites for academics with R

  • building a minimal working site
  • version-controlling and deploying it
  • adding new content to the site

• Based on personalising the example website of the Academic theme, with two options

  • using real material, creating your website now
  • using mock material, re-creating the demonstration website of the workshop*
    • as a practice for creating your website afterwards

The Workshop — Overview

• One full day, on how to create websites for academics with R

  • building a minimal working site
  • version-controlling and deploying it
  • adding new content to the site

• Based on personalising the example website of the Academic theme, with two options

  • using real material, creating your website now
  • using mock material, re-creating the demonstration website of the workshop
    • as a practice for creating your website afterwards

• Designed for researchers with basic knowledge of R programming language

  • ability to work with R and RStudio will be very helpful
    • but not absolutely necessary — these skills can be developed after the workshop as well

The Workshop — Motivations

• Academic outreach

  • make your work easily accessible to other academics
  • keep all academic work at one address
  • offer versions without paywall
    • e.g., pre-prints

• Public outreach

  • make your work easily accessible to non-academics, in two senses
  • by removing paywalls
    • e.g., pre-prints
      
      
  • by writing for non-academic audience in mind
    • e.g., blogposts

The Workshop — Motivations — Impression Management

• What do people see when they google your name?

  • google your name now, and scroll through
    • is this exactly what you want people to see?

• Websites are an impression management tool
  
  
  • manage your online presence yourself
    • otherwise, others --- e.g., your (past and present) university --- will
      
      
  • provide a concrete example of your skills
    • e.g., working with R, Git

The Workshop — Aims

• To leave you with a website

  • working, continuously deployed from RStudio
  • albeit minimal and/or mock

• To make you aware what else is possible

  • so that you can update your website after the workshop
  • awareness of what is possible, Google, and perseverance are all you need

The Workshop — Limitations

This workshop does not cover

• dynamic websites

  • it covers static websites, as generated by Hugo, as integrated into R by blogdown
    • all visitors see the same website, as last generated
    • this setting offers what most academics would need

• structural (HMTL, CSS, or JavaScript) customisation

  • e.g., changing the entire appearance and functionality of a theme, writing a new one
  • switching to another Hugo theme is an option
    • see 300+ options at https://themes.gohugo.io/

• multi-language or multi-author websites

  • these are possible, and well documented elsewhere
    • e.g, for multi-lingual websites, see https://sourcethemes.com/academic/docs/language/
    • e.g., for multi-author websites, see my workshop on collaboration

The Workshop — Organisation

• Sit in groups of two

  • participants learn as much from their partner as from instructors
  • play the role of co-authors

• Type, rather than copy and paste, the code that you will find on these slides

  • typing is a part of the learning process
  • but do copy the text from JJD's website, if you are re-creating it

• When you have a question

  • ask your partner
  • google together
  • turn your microphone on and ask, or
  • type it in the chat

The Workshop — Organisation — Slides

• Codes and texts that go in as input appear as such — in a different font, on gray background
  • long codes and texts will have their own line(s)

ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) +
  geom_point(size = 2) +
  scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7",
                        breaks = c(4, 6, 8)) +
  theme_bw() +
  theme(axis.title = element_text(size = 20),
        axis.text = element_text(size = 20),
        legend.title = element_text(size = 20),
        legend.text = element_text(size = 20)) +
  labs(x = "\nWeight", y = "Miles/Gallon\n")

The Workshop — Organisation — Slides

• Codes and texts that go in as input appear as such — in a different font, on gray background
  • long codes and texts will have their own line(s)

• Results that come out as output appear as such — in the same font, on green background
  • except very obvious results, such as figures and tables

• Specific sections are highlighted yellow as such for emphasis
  • these could be for anything — codes and texts in input, results in output, and/or texts on slides

• Names for items such as files, folders, variables are in typefont.
  • typefont with a trailing slash indicates a directory, known also as folder
    • e.g., content/ is a directory

The Workshop — Contents

blogdown — Overview

• A relatively small R package, to facilitate creating websites
  • enables a seamless workflow, all within RStudio
  • does not build websites itself

• Builds upon other software
  • most importantly Hugo for generating sites
  • (R) Markdown for text formatting
  • pandoc for transforming Markdown files into HTML
  • YAML syntaxes for configuration and front matter

• Has a confusing name
  • it is not necessarily about blogs, but general-purpose websites

• Comes with a book
  • blogdown: Creating Websites with R Markdown (Xie et al., 2021b)
    • open access at https://bookdown.org/yihui/blogdown/
    • also has a confusing name, as R Markdown is not central to creating websites

blogdown — Addins

blogdown — Important Fuctions

• blogdown provides functions to facilitate interacting with Hugo from within R, including
  • blogdown::install_hugo()
  • blogdown::serve_site()

• It is customary to call blogdown functions with the double colon operator ::
  • the usual way would also work
    • i.e., load library(blogdown) first

• To see the list of exported functions, type blogdown:: in the Console
  • hit the tab key on your keyboard

Other Resources — For Later

• R Markdown: The Definitive Guide (Xie et al., 2019)

  • open access at https://bookdown.org/yihui/rmarkdown

• R Markdown Cheat Sheet

  • follow from the RStudio menu

Help -> Cheatsheets -> R Markdown Cheat Sheet

• Pandoc User's Guide

  • available at https://pandoc.org/MANUAL.html

• R for Data Science (Wickham and Grolemund, 2019)

  • open access at https://r4ds.had.co.nz

Academic — Overview

Academic — Demonstration Site

• The homepage is composed of different parts, called widgets
  • e.g., the sections titled Biography, Experience, Accomplishments etc.

• Some menu items direct the screen to different widgets on the homepage
  • e.g., Demo, Posts, Projects etc.

• Other menu items direct to stand alone sections
  • e.g., Courses

• The menu also has a search function and a day/night mode switch

Academic — Advantages

• Designed especially for academics in mind
  • features what academics would want to feature
    • e.g., education, publications

• Well looked after
  • gets updated very frequently
    • Hugo released v0.71.1 on Monday 25 May 2020, which broke the theme
    • Academic got updated the next day with a fix
  • has a lively community of users and developers behind it

• Well documented
  • every line of code in the example site is commented in the backend
  • more documentation available at https://sourcethemes.com/academic/docs/

Academic — Disadvantages

• Complicated

  • with its high customisation, comes high complexity
  • its widgets can at first be overwhelming

• Popular

  • over 100,000 websites use this theme
  • hard to stand out in this crowd

Academic — Disadvantages

• Complicated but well documented
  • with its high customisation, comes high complexity
  • its widgets can at first be overwhelming
  • you can handle it on your own

• Popular but with room for personalisation
  • over 100,000 websites use this theme
  • hard to stand out in this crowd
  • it comes with different colour schemes, fonts
  • there are many potential combinations of widgets

Website Backend — Directory Structure

Website Backend — Directory Structure

Website Backend — Directory Structure

Website Backend — Directory Structure — /content/

• Observe that the files under /content/ are typically Markdown files

  • with the .md extension

• These files have typically two sections

  • a front matter with the YAML syntax
    • YAML goes between a pair of three hyphens ---
      
      
  • and some text
    • using Markdown syntax

Website Backend — Directory Structure

Website Backend — Directory Structure — Notes

• Hugo websites follow more or less the same directory structure

  • see the Hugo documentation for directory structure at https://gohugo.io/getting-started/directory-structure/
  • structure might look slightly different in different themes
    • e.g., less complex themes have one configuration file only, without /config/

• The structure, as well as other technical details, might change

  • changes come with a new Hugo version
  • a change may or may not break a theme
  • themes are designed, and websites are generated, with a certain version
    • these two versions do not have to be the same, but compatible

Configuration — Overview

• There are four configuration files in the theme

  • /config.yaml
  • /config/_default/languages.yaml
  • /config/_default/menus.yaml
  • /config/_default/params.yaml

• These files are for overall definitions, settings, and organisation

  • e.g., creating menu items; defining font, language
  • these files are written with the YAML syntax

• We will work with the existing options of in these files

  • for the complete list of options that you can use in configuration files, see https://gohugo.io/getting-started/configuration

Configuration — YAML Syntax

 title: "Jane J. Doe"

Configuration — YAML Syntax

 title: "Jane J. Doe"

Configuration — YAML Syntax

 title: "Jane J. Doe"
 summaryLength: 30

Configuration — YAML Syntax

 title: "Jane J. Doe"
 summaryLength: 30
 enableEmoji: true

Configuration — YAML Syntax

 title: "Jane J. Doe"
 summaryLength: 30
 enableEmoji: true
 interests:
  - Party politics
  - Public policy
  - International polities

Configuration — YAML Syntax — Notes

There is an alternative way to write sequence of values

• in square brackets, separated by comma

 title: "Jane J. Doe"
 summaryLength: 30
 enableEmoji: true
 interests: [Party politics, Public policy, International polities]

Configuration — YAML Syntax — Notes

Multiple nesting of keys and sequences is also possible

• requires indentation with four spaces for the first nesting, and an hyphen for the second

 education:
     courses:
         - course: PhD in Political Science
           institution: University of Vienna
           year: 2017
         - course: MSSc in European Studies
           institution: University of Tampere
           year: 2009

Configuration — YAML Syntax — Notes

To disable an option in YAML, you can

• comment its line out with a hash

# title: "Jane J. Doe"

• set it to []
  • this may not work in nests

title: []

• set it to ""

title: ""

• delete it altogether
  • not recommended, as you might need that key in the future

Configuration — menus.yaml

This file configures the website menu

• creates and orders menu items
• directs them
  • to a specific section on the homepage
    • e.g., to a widget such as Contact at the bottom of the homepage
      
      
  • to a specific page
    • e.g., to a page that lists the titles of all blogposts
    • e.g., to a specific blogpost

Configuration — menus.yaml

main
  - name: "Posts"
  - name: "Courses"
  - name: "Twitter"
  - name: "CV"

Configuration — menus.yaml

main
  - name: "Posts"
    weight: 10
  - name: "Courses"
    weight: 30
  - name: "Twitter"
    weight: 20
  - name: "CV"
    weight: 40

Configuration — menus.yaml

main:
  - name = "Posts"
    weight = 10
    url = "#posts"
  - name = "Courses"
    weight = 30
    url = "courses/"
  - name = "Twitter"
    weight = 20
    url = "https://twitter.com/resulumit"
  - name = "CV"
    weight = 40
    url = "files/cv.pdf"

Configuration — languages.yaml

This file

• defines the language of the website

  • the default is English

• can make the site multi-lingual

  • we will not cover it in this workshop
  • instructions available at the above link as well

Configuration — Multi-lingual Sites

• Considerations
  
  
  • who is your target audience?
    • would they be lost if your website was only in one language?
      • if not, perhaps it is not worth the hassle
        
        
  • what will be in multiple languages?
    • all website, or some widgets and/or pages?
      • even in a single language setting, widgets and pages can be written in different languages

• Strategy

  • build your website in full in one language first, than add the second
    • rather then building it multiple languages in tandem
    • hence not covered in the workshop

Structure — Overview

• Structure depends mostly on the way the /content/ directory is organised, including

  • individual pages, such as a homepage
  • sections (collections of pages), such as a blog

• Each page at the fronted corresponds to a Markdown file at the backend

  • changing the content and/or the position of these files at the backend will change the frontend

• Sections are organised in separate directories under /content/

  • first-level sub-directories become a section by default
    • e.g. content/post/ is a section (for all blogposts)
      
      
  • creating a section under a section requires manual input
    • by adding a file named _index.md under the second-level directory

Structure — Examples

A website with a single page

.
└── /content/
    |
    └── home.md          # <- https://janejdoe.netlify.app/home/

Structure — Examples

A website with two single pages

.
└── /content/
    |
    ├── home.md          # <- https://janejdoe.netlify.app/home/
    |
    └── about.md         # <- https://janejdoe.netlify.app/about/

Structure — Examples

A website with five pages

.
└── /content/
    |
    ├── home.md             # <- https://janejdoe.netlify.app/home/
    |
    ├── about.md            # <- https://janejdoe.netlify.app/about/
    |
    └── blog/               # <- https://janejdoe.netlify.app/blog/
        |
        ├── first-post.md   # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── second-post.md  # <- https://janejdoe.netlify.app/blog/second-post/

Note that there are

• four single pages: home, about, first-post, second-post
• one section page: blog
  • because it is a first order sub-directory
  • by default, this section page is tiled Blog, showing the links to the two posts

Structure — Examples

A website with three pages

.
└── /content/
    |
    ├── home.md             # <- https://janejdoe.netlify.app/home/
    |
    ├── about.md            # <- https://janejdoe.netlify.app/about/
    |
    └── blog/index.md       # <- https://janejdoe.netlify.app/blog/

Note that

• index.md is a special file name for Hugo — it creates a page matching its directory name
• there are three single pages: home, about, blog
• blog is not a section page, but a simple page, showing a blogpost

Structure — Examples

A website with five pages: three three single pages and two nested section pages

.
└── /content/
    |
    ├── home.md              # <- https://janejdoe.netlify.app/home/
    |
    └── blog/                # <- https://janejdoe.netlify.app/blog/
        |
        ├── first-post.md    # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── academic/        # <- https://janejdoe.netlify.app/blog/academic/
          |
          ├── _index.md   
          |
          └── second-post.md    # <- https://janejdoe.netlify.app/blog/academic/second-post/

Structure — Examples

A website with five pages: three single pages and two nested section pages

.
└── /content/
    |
    ├── home.md              # <- https://janejdoe.netlify.app/home/
    |
    └── blog/                # <- https://janejdoe.netlify.app/blog/
        |
        ├── first-post.md    # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── academic/        # <- https://janejdoe.netlify.app/blog/academic/
          |
          ├── _index.md   
          |
          └── second-post.md    # <- https://janejdoe.netlify.app/blog/academic/second-post/

Structure — Examples

A website with five pages: three single pages and two nested section pages

.
└── /content/
    |
    ├── home.md              # <- https://janejdoe.netlify.app/home/
    |
    └── blog/                # <- https://janejdoe.netlify.app/blog/
        |
        ├── first-post.md    # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── academic/        # <- https://janejdoe.netlify.app/blog/academic/
          |
          ├── _index.md  
          |
          └── second-post.md    # <- https://janejdoe.netlify.app/blog/academic/second-post/

Structure — Examples

A website with five pages: three single pages, two nested section pages

.
└── /content/
    |
    ├── home.md              # <- https://janejdoe.netlify.app/home/
    |
    └── blog/                # <- https://janejdoe.netlify.app/blog/
        |
        ├── first-post.md    # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── academic/        # <- https://janejdoe.netlify.app/blog/academic/
          |
          ├── _index.md  
          |
          └── second-post.md    # <- https://janejdoe.netlify.app/blog/academic/second-post/

Notice that

• _index.md, with underscore, is a special file name for Hugo — it creates sections

Structure — Examples

Having _index.md in first-order sub-directories is optional, but may be helpful

• can add metadata and/or text to section pages
  • e.g., these are by default titled as the plural of section names
    • e.g., the page publication/ is titled as Publications
  • change this behaviour with _index.md

.
└── /content/
    |
    └── home.md             # <- https://janejdoe.netlify.app/home/
    |
    └── about.md            # <- https://janejdoe.netlify.app/about/
    |
    └── blog/               # <- https://janejdoe.netlify.app/blog/
        |
        ├── _index.md
        |
        ├── first-post.md   # <- https://janejdoe.netlify.app/blog/first-post/
        |
        └── second-post.md  # <- https://janejdoe.netlify.app/blog/second-post/

Structure — home/ — Overview

• The homepage in Academic does not exactly follow the structure above

  • every file under home/ is not a stand alone page
  • these files, called widgets, are rather stitched under one another
    • considered as one of the strengths of the theme
    • some academics prefer to have only this page

• Widgets are complicated Markdown files

  • can be stitched under one another
  • can get text from files elsewhere
    • e.g., the contact.md widget gets the address information from params.yaml

• A homepage can have one, more, or all widgets

  • widgets can be deactivated or repeated
  • they can be re-ordered as well

Structure — home/ — Widgets

• There are 13 types of pre-defined widgets

  • for detailed explanations, see https://sourcethemes.com/academic/docs/page-builder/
  • you can build your own widget as well

• Widgets are in fact Markdown files, with .md extension

  • each has YAML syntax as the front matter
  • some has Markdown text as well
    • e.g., demo.md
  • because they can have both variables and text, YAML goes between a pair of three hashes

• Widgets are located under /content/home/

  • except index.md, each file is a widget — some duplicates of the same type

Structure — Homapage — Widgets — Important Keys

 widget: "pages"

Structure — Homapage — Widgets — Important Keys

 widget: "pages"
 active: false

Structure — Homapage — Widgets — Important Keys

 widget: "pages"
 active: false
 weight: 9

Structure — Homapage — Widgets — Important Keys

 widget: "pages"
 active: false
 weight: 9
 title: "Recent Publications"
 subtitle: ""

Structure — Homapage — Widgets — Important Keys

 widget: "pages"
 active: false
 weight: 9
 title: "Recent Publications"
 subtitle: ""
 page_type: "publication"

Structure — Homapage — Widgets — Important Keys

 widget: "pages"
 active: false
 weight: 9
 title: "Recent Publications"
 subtitle: ""
 page_type: "publication"

Structure — Adding

• There are at least three ways to add new pages and sections

  • create new files and directories, respecting the directory structure of Hugo and Academic
  • rename and edit the existing files and folders for your purposes
  • duplicate, rename, and edit the existing files and folders that are in use

• RStudio has helpful buttons for these purposes
  • to create, duplicate, and/or rename
  • alternatively, use your operating system

Structure — Removing

There are at least two ways to remove pages and sections

• delete them, respecting the directory structure of Hugo and Academic
  • perhaps, you are sure there will not be two authors on your website
    • the example site comes with two author profiles, under /content/authors/
    • with usernames admin (main) and 吳恩達 (secondary)
    • it is safe to delete the latter
      
      
• turn them into drafts, by setting
  • active: false in the YAML of widgets
  • draft: true in the YAML of other Markdown files
  • perhaps, you think you may need a section in the future

Structure — Removing — Non-Widget Markdown

• You can deactivate a specific page in a section

  • add draft: true to file of that page
  • e.g., /content/publication/journal-article/index.md

• You can deactivate whole sections in one go

  • add draft: true to file of that section
  • e.g., /content/publication/_index.md

• You can deactivate whole sections except one or more pages

  • add draft: true to file of that section
  • e.g., /content/publication/_index.md
    
    
  • add draft: false to the file of a page
  • e.g., /content/publication/journal-article/index.md

Structure — Removing — Non-Widget Markdown

• Not all sections have _index.md to start with

  • e.g., /content/project/
  • you can add one, following

File -> New File -> R Script

• Draft pages and sections are still visible to you in live preview

  • e.i., when you use blogdown::serve_site
  • but not to the visitors of your website
    • e.i., if you publish your site

Deployment — Overview

• Deployment of your website onto a web server makes it visible online

  • your website is currently available on your computer only

• You can deploy your website at any web server that you prefer

  • Netlify is a popular choice as a web server
    • easy to set up
    • includes a free plan
    • recommended by the authors of the blogdown package and the Academic theme

Deployment — Workflow

Deployment occurs in two steps

• we push the website files, from our computer, into a GitHub repository

  • for the first time, and after one or more edits
  • with commands or clicks in RStudio

• Netlify does the rest automatically, in a minute or so

  • (re-)retrieves the files
  • generates the website with Hugo
  • (re-)publishes the website

Deployment — Git and GitHub — Definitions

• Git
  • a software that keeps track of versions of a set of files
  • it is local, the records are kept on your computer

• GitHub
  • a hosting service, or a website, that can keep the records
  • it is like Dropbox, but specifically structured to keep records with Git

• Repository, or repo
  • a set of files whose records are kept together, by Git and/or on GitHub
  • it is like a folder, which can keep files and other folders containing files

Deployment — Git and GitHub — Definitions

• To commit
  • to take a snapshot of, to version a repository
  • it is like saving a new version of all changed files in your folder with a new name
  • it is local, the records are kept on your computer unless you push

• To push
  • to move the records from Git to GitHub, from your computer to online
  • it is like uploading (the new versions of) your files to a website,
  • it also involves merging, if this not the first push

• To pull
  • to move the updated records from GitHub to your computer
  • it is like downloading a zipped folder of files, and merging with the ones on your computer

Deployment — Git and GitHub — Workflow

Working with with Git and GitHub requires

• initial setup, done once^*
  • unless for a new computer or, if ever, a new GitHub account
  • a bit technical, but worth the hassle

• project setup, repeated for every RStudio project
  • shorter, less complicated

Deployment — Notes

• Avoid pushing your project to GitHub without checking it works locally first
  • use blogdown for your advantage, observe it in Viewer

• If things still go wrong, you can revert back to the version on GitHub
  • git checkout HEAD PATH/TO/FOLDER/OR/FILE reverts a specific folder or file
  • git reset --hard reverts all

• Note that
  • reverting as above gets rid of good as well as bad edits
    • more nuanced approaches are possible
  • reverting further back to one of the previous versions also possible
  • see my workshop materials on working with with Git and GitHub for more information

Content — Overview

Most of what is visible at website frontend is stored in three directories at the backend

• some files are under the /assets/ directory
  • most importantly, the website icon

• other display-as-is materials are under the /static/ directory
  • e.g., PDFs, images

• most materials are under the /content/ directory
  • e.g., Markdown files matching pages, widgets for the homapage

Content — /assets/

• This directory stores non-textual files to be processed
  • by Hugo to generate the website
  • e.g., images

• By default, files under /assets/ do not have a matching URL
  • visitors will not be able to view them unprocessed on a browser

• Adding a file to /assets/ is straightforward
  • move or copy into it as normal

• Academic looks in /assets/media/ for a website icon
  • it appears, e.g., on web browser tabs
  • it must be named icon.png
  • if not, Academic uses the default icon

Content — /static/

• This directory stores non-textual files not to be processed
  • Hugo simply copies these files over to frontend
  • e.g., images

• By default, files under /static/ have a matching URL
  • visitors will be able to view them unprocessed on a browser

.
└── /static/
    |
    └── pfofile-photo.jpg     # <- https://janejdoe.netlify.app/pfofile-photo.jpg 
    |
    └── files/                           
        |
        └── cv.pdf         # <- https://janejdoe.netlify.app/files/cv.pdf

Content — /static/

• This directory stores non-textual files not to be processed
  • Hugo simply copies these files over to frontend
  • e.g., images

• By default, files under /static/ have a matching URL
  • visitors will be able to view them unprocessed on a browser

• Adding a file to /static/ is straightforward
  • move or copy into it as normal

• /static/ is the right directory to store PDFs
  • e.g., cv, publications

Content — /content/

• This directory stores mostly textual files to be processed

  • mostly by Hugo, some by blogdown
  • e.g., Markdown files

• Most files under this directory are plain Markdown files

  • with the .md extension
  • transformed by Blackfriday — Hugo's Markdown rendering engine, so is Netlify's — into HTML
    • no need for blogdown, but cannot execute any code

• Some are R Markdown files

  • with either .Rmd or .Rmarkdown extension
    • transformed by pandoc — blogdown's rendering engine
      • therefore can execute code, thanks to blogdown
    • we will cover these in Part 8

Content — Markdown Syntax — Overview

• Markdown is a plain-text file

  • with its own syntax
    • much easier to write than HTML
    • the differences between plain and R Markdown syntaxes are minimal
  • versatile, can be transformed into many different formats, including HTML

• Plain Markdown (.md) follows Blackfriday's Markdown syntax

  • a useful guide to the basic MArkdown syntax is available at https://www.markdownguide.org/basic-syntax/
  • a small number of Blackfriday-specific extensions are available at https://github.com/russross/blackfriday

• R Markdown (.Rmd and .Rmarkdown) follows the syntax in Pandoc's Markdown

  • for the complete rules of the syntax, see Pandoc User's Guide
  • for a useful summary of the syntax, see the R Markdown Cheat Sheet

Content — Markdown Syntax — Strategies

• There are at least two different strategies to deal with .md versus .Rmd dilemma

  • use .md for pages with no data, .Rmd for pages with data

    • maximises the functionality from each
    • requires learning the small differences if necessary

  • use .Rmd for all pages

    • requires learning only one syntax
    • misses the additional functionality in .md
    • folders get cluttered with intermediate files

• The syntax in the following slides of this section will work with both types

  • unless otherwise stated
    • e.g., see tasks lists

Content — Markdown Syntax — Lines

Multiple spaces on a given line are reduced to one

This is a sentence followed by four spaces.    This is another sentence on the same line.

This is a sentence followed by four spaces. This is another sentence on the same line.

Line endings with fewer than two spaces are ignored

This is a sentence followed by one space.
This is another sentence on a new line.

This is a sentence followed by one space. This is another sentence on a new line.

Content — Markdown Syntax — Hard Brakes

Two or more spaces at the end of lines introduce hard brakes, forcing a new line

This is a sentence followed by two spaces.  
This is another sentence on a new line.

Content — Markdown Syntax — Block Quotes

Lines starting with the grater-than sign > introduce block quotes

> In God, we trust. All others must bring data. 
>
> --- Anonymous

Content — Markdown Syntax — Paragraphs

One or more^* blank lines introduce a new paragraph

This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line. 
This is the first sentence of a *new paragraph* as it is preceded by a blank line. This is the 
second sentence of that paragraph, which is followed by a blank line.

Content — Markdown Syntax — Comments

Text with the syntax <!--comments --> is omitted from output

<!-- This paragraph needs re-writing -->
This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line. 
This is the first sentence of a new paragraph <!-- I've removed italics --> as it is preceded 
by a blank line. This is the second sentence of that paragraph, which is followed by a blank 
line.

Content — Markdown Syntax — Headers

The number sign # introduces headers; lower levels are created with additional signs — up to total five levels

Content — Markdown Syntax — Emphases

A pair of single asterisk * or underscore _ introduces italics

*italics* becomes italics

_italics_ becomes italics as well

A pair of double asterisks or underscores introduces bold

**bold** becomes bold

__bold__ becomes bold as well

These two rules can be combined

**_bolditalics_** becomes boldsitalics

_**bolditalics**_ becomes bolditalics as well

Content — Markdown Syntax — Strikethrough

A pair of double tildes ~ introduces strikethrough

~~strikethrough~~ becomes strikethrough

Strikethrough can be combined with italics or bold

**~~strikebold~~** or __~~strikebold~~__, they both become strikebold

~~**strikebold**~~ or ~~__strikebold__~~, they both become strikebold as well

*~~strikeitalitcs~~* or _~~strikeitalitcs~~_, they both become strikeitalitcs

~~*strikeitalitcs*~~ or ~~_strikeitalitcs_~~, they both become strikeitalitcs as well

Content — Markdown Syntax — Links — Internal^*

You can link text to section headers in the same document

[Conclusion](#conclusion) becomes Conclusion, and a click takes the screen to that section

Multi-word headers need hyphenation

[Literature Review](#literature-review) becomes Literature Review, and it works only if the second part is hyphenated

Content — Markdown Syntax — Links — External

You can link text to URLs

[click here](https://janejdoe.netlify.app/) becomes click here

<https://janejdoe.netlify.app> becomes https://janejdoe.netlify.app

[https://janejdoe.netlify.app](https://janejdoe.netlify.app/) becomes

https://janejdoe.netlify.app as well

You can also link text to email addresses

[email me](mailto:j.j.doe@kriens.edu)^* becomes email me

<j.j.doe@kriens.edu> becomes j.j.doe@kriens.edu

Content — Markdown Syntax — Footnotes

Use the [^identifier] syntax, with identifiers defined elsewhere in the same document, to create a footnote

Dr Doe holds a PhD in rock science.[^1]
[^1]: She defended her thesis in 2017.

Dr Doe holds a PhD in rock science.¹

Content — Markdown Syntax — Lists

Lines starting with asterisk * as well as plus + or minus − signs introduce lists

- books
- articles
- reports

Content — Markdown Syntax — Lists — Nesting

Lists can be nested within each other, with indentation

+ books
+ articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

Content — Markdown Syntax — Lists — Numbering

List items can be numbered

1. books
2. articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

Content — Markdown Syntax — Lists — Numbering

List items can be numbered

1. books
2. articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

Content — Markdown Syntax — Lists — Tasks Lists

Task lists can be created in plain Markdown, but not in R Markdown

- [x] books
- [ ] articles
    - [ ] published
    - [x] under review
        + [x] revised and resubmitted
    - [ ] work in progress

Content — Markdown Syntax — Dashes

Two hyphens grouped together introduce an en-dash

‐‐ becomes –

Three hyphens grouped together introduce an em-dash

‐‐‐ becomes —

Content — Markdown Syntax — Highlithing

Highlight any piece of text, by putting it in between a pair of backticks `

`code` becomes code

Highlight blocks of text by putting them in between two lines, each starting with three backticks ```

```
df <- mtcars %>% 
      filter(gear > 3)
```

becomes

df <- mtcars %>% 
      filter(gear > 3)

Content — Markdown Syntax — Tables

The following syntax introduces hand-made tables

|First Column | Second Column | 
|------------ | ------------- |
|First cell   | First cell    |  
|Second cell  | Second cell   |
|Third cell   | Third cell    |

Note that

• R Markdown makes it possible to customise hand-made tables futher
  • we will cover these in Part 8

Content — Markdown Syntax — Images

The syntax  embeds images into HTML outputs

• similar to the link syntax, only this time it is preceded by an exclamation mark !
• goes a new line, separate from the text
• assumes the figure is in the same folder with the Markdown file^*

Content — Images — Markdown Syntax

![](/media/boards.jpg)

Content — Images — Notes

• Images can also be added through YAML
  • e.g., to blogposts, publications
  • using the image key

• These images must be saved in the same directory
  • as featured.jpg
  • rename or remove it if having them is not desireble
    • removing the image key in YAML is not effective

R Markdown — Overview

• R Markdown is a special type of Markdown
  • can run code, and embed the results from data into HTML
  • have the .Rmd or .Rmarkdown extension

• Hugo cannot transform R Markdown into HTML
  • that is why we need the blogdown package
  • transformation of these files takes places locally on your computer
  • not remotely at the server — e.g., Netlify

• R Markdown is very similar to Markdown in terms of syntax
  • except that it includes code
    • mostly R code, but could also be python

R Markdown — Code — Overview

Most codes go inside code chunks

• e.g., code that imports and cleans data, and/or produces tables and/or figures

```{r}
df <- mtcars %>%
      mutate(disp_litre = disp / 61.0237)
```

Codes can also go in line with text

• .e.g., code that result in a single statistic

The average engine displacement of the cars in the dataset is `r mean(df$disp_litre)` litres.

R Markdown — Code Chunks — Overview

• Code chunks are delimited spaces between a pair of three backticks
  • below is an empty chunk for R code

```{r}
```

• r is an option of the chunk, indicating that the code in the chunk above should be run by R
  • it could have been python, which we will not cover in this workshop
  • options go in a pair of curly brackets, on the same line with the first delimiter

• Chunks can be placed anywhere in .Rmd documents
  • their output will be placed instead of, or following,^* the code chunk on the website page

R Markdown — Code Chunks — Labels

Label the code chunks right after r

```{r, tidydata}
df <- mtcars %>%
      mutate(disp_litre = disp / 61.0237)
```

Note that

• labels are optional, but recommended because they
  • can be used in text, to refer to tables or figures that code chunks produce
  • can help with navigating through error messages
    
    
• duplicate labels lead to an error

R Markdown — Code Chunks — Options

• Code chunks take options, listed on the same line with the first delimiter, in curly brackets

  • avoid spaces around the equal sign = between option tags and values
    • such spaces might lead to errors
      
      
  • in the example below, the chunk is labelled as setup, and and the include option is set to FALSE
    • with this option and value, nothing from this chunk will be included in the output document

```{r, tidydata, include=FALSE}
```

• The list of options is available at https://yihui.org/knitr/options

  • R Markdown Cheat Sheet provides a helpful list as well

R Markdown — Code Chunks — Options — Defaults

Options have default values

• e.g., for echo, the default is TRUE
  • echo: should the source code printed in the output? — yes
    
    
• therefore the following two chunks have the same function

```{r, tidydata}
```

```{r, tidydata, echo=TRUE}
```

R Markdown — Code Chunks — Options — Defaults

This chunk prints two things in the output document — (a) the code and (b) the head of the data frame

```{r, headdata}
head(df)
```

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb disp_litre
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4   2.621932
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4   2.621932
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1   1.769804
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1   4.227866
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2   5.899347
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1   3.687092

R Markdown — Code Chunks — Options

Setting echo=FALSE prevents the code from being displayed in the output document

```{r, headdata, echo=FALSE}
head(df)
```

This chunk therefore prints one thing in the output document — the head of the data frame

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb disp_litre
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4   2.621932
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4   2.621932
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1   1.769804
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1   4.227866
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2   5.899347
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1   3.687092

R Markdown — Code Chunks — Other Useful Options

Prevent the result(s) of the source code from being displayed in the output document

```{r, headdata, results="hide"}
head(df)
```

This chunk therefore prints one thing in the output document — the source code

R Markdown — Code Chunks — Other Useful Options

Cache results for future compilations

```{r ... cache=TRUE}
```

Prevent R from running the code in the chunk altogether

```{r ... eval=FALSE}
```

Prevent messages and/or warnings from being displayed in the output

```{r ... error=FALSE, message=FALSE, warning=FALSE}
```

R Markdown — Code Chunks — Other Useful Options

Define the actual dimensions of figures, in inches

```{r ... fig.height=6, fig.width=9}
```

Define the size of figures in the output document, with out.width and/or out.height

```{r ... out.width="50%"}
```

Define the alignment of figures — left, right, or center

```{r ... fig.align="center"}
```

R Markdown — Code Chunks — Other Useful Options

Define captions for figures

```{r ... fig.caption="A Scatter Plot"}
```

Set the resolution for figures

```{r ... dpi=300}
```

Set extra options, which rmarkdown will write into the <img /> tag

```{r ... out.extra='style="display:block;"'}
```

R Markdown — Code Chunks — The Setup Chunk

It is recommended to use the first code chunk for general setup, where you can

• define your own defaults for chunk options, with knitr::opts_chunk$set()
  • avoids repeating chunk options
    
    
• load the necessary packages
  
  
• import raw data

```{r, setup, include=FALSE}
# chunk option defaults
knitr::opts_chunk$set(echo=FALSE, message=FALSE)
# packages
library(dplyr)
library(ggplot2)
library(knitr)
# data
df_raw <- mtcars
```

R Markdown — Code Chunks — The Setup Chunk — Data

Note that the data source can be anywhere that R can access

```{r, setup, include=FALSE}
...
# this dataset is available online
df_online <- read.csv("http://www.parlgov.org/static/data/development-cp1252/view_party.csv")
# this dataset is in the same directory as my .Rmd file
df_local <- read.csv("view_cabinet.csv")
```

R Markdown — Code Chunks — The Data Chunk

I recommend using the second chunk for the main operations^* on raw data

• e.g., for data cleaning and other transformations
• some minor transformations could be left to lower chunks
  • e.g., capitalizing variable names for figures

```{r, data, echo=FALSE ...}
df <- df_raw %>%
      mutate(disp_litre = disp / 61.0237)
```

R Markdown — Inline Code — Overview

Code can also be incorporated in text, with the `r ` syntax

• unlike chunks, these do not take options
  
  
• the output document will display the result of the code
  • in the exact place of the source code
    
    
• the result of the code will have the same formatting with the text

R Markdown — Inline Code — Examples

If we multiply _pi_ by 5, we get `r pi * 5`.

If we multiply pi by 5, we get 15.7079633.

The average the engine displacement of the cars in the dataset is `r mean(df$disp_litre)` 
litres, which would round to `r round(mean(df$disp_litre), digits = 1)`.

The average the engine displacement of the cars in the dataset is 3.7808569, which would round to 3.8.

__Only `r nrow(subset(df, gear == 5))` cars__ in the dataset have five forward gears.

Only 5 cars in the dataset have five forward gears.

R Markdown — Figures

Place code that produces figures in code chunks

```{r, scatterplot, fig.cap = "A scatterplot of cars.", echo=FALSE}
ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) +
  geom_point() +
  scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7",
                        breaks = c(4, 6, 8)) +
  labs(x = "Weight", y = "Miles/Gallon") +
  theme_bw()
```

R Markdown — Figures — Cross-References

Use the following syntax to refer to figures

See Figure \@ref(fig:scatterplot) below.

```{r, scatterplot, fig.cap = "A scatterplot of cars.", echo=FALSE}
ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) +
  geom_point() +
  scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7",
                        breaks = c(4, 6, 8)) +
  labs(x = "Weight", y = "Miles/Gallon") +
  theme_bw()
```

R Markdown — Tables —

Place code that produces HTML tables in code chunks

```{r, headdata, echo=FALSE}
kable(head(df, 3), caption = "First three rows in the dataset")
```

Table 1. First three rows in the dataset.

R Markdown — Tables — Cross-References

Use the following syntax to refer to tables

See Table \@ref(tab:headdata) below.

```{r, headdata, echo=FALSE}
kable(head(df, 3), caption = "First three rows in the dataset")
```

See Table 1 below.

                    Table 1. First three rows in the dataset.

R Markdown — Tables — Hand-Made

The following syntax, outside code chunks, introduces tables^*

First Column  Second Column 
------------  ------------- 
First cell    First cell      
Second cell   Second cell   
Third cell    Third cell

R Markdown — Tables — Hand-Made

The position of headers, relative to their line underneath, defines column alignments

Left-Aligned          Centered   
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell

R Markdown — Tables — Hand-Made

A line starting with a colon, placed before or after tables, introduces captions

    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell  
: A hand-made table with R Markdown

R Markdown — Tables — Hand-Made

The caption line itself needs to be surrounded by empty lines

    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell  
   
: A hand-made table with R Markdown                                      

R Markdown — Tables — Hand-Made

Tables are numbered automatically

: A hand-made table with R Markdown 
    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell

R Markdown — Tables — Hand-Made

Grid tables, with the following syntax, can handle complex cells with multiple lines and/or lists

+--------------------+--------------------+
| First Column       | Second Column      | 
+====================+====================+
| - First item       | First cell         | 
| - Second item      |                    | 
| - Third item       |                    |
+--------------------+--------------------+
|Second cell         | Second cell with a | 
|                    | long text          | 
+--------------------+--------------------+
| Third cell         | Third cell         | 
|                    |                    | 
+--------------------+--------------------+
: A grid table with multi-line cells

R Markdown — Tables — Hand-Made

Grid tables can be aligned as well, with colons at the boundaries of the header separator^*

+--------------------+--------------------+
| Left-Aligned       | Centered           | 
+:===================+:==================:+
| - First item       | First cell         | 
| - Second item      |                    | 
| - Third item       |                    |
+--------------------+--------------------+
|Second cell         | Second cell with a | 
|                    | long text          | 
+--------------------+--------------------+
| Third cell         | Third cell         | 
|                    |                    | 
+--------------------+--------------------+
: A grid table with multi-line cells

R Markdown — Tables — Hand-Made — Cross-References

Use the following syntax to refer to hand-made tables

See Table \@ref(tab:handmade) below.

    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell  
: (\#tab:handmade) A hand-made table with R Markdown

References

Dowle, M. and Srinivasan, A. (2021). data.table: Extension of 'data.frame'. R package, version 1.14.0.

Sievert, C., Parmer, C., Hocking, T., Chamberlain, S., Ram, K., Corvellec, M., & Despouy, P. (2021). plotly: Create Interactive Web Graphics via 'plotly.js'. R package, version 4.9.3.

Wickham, H. and Grolemund, G. (2019). R for data science. O'Reilly. Open access at https://r4ds.had.co.nz.

Wickham, H., Chang, W., Henry, L., Pedersen, T. L., Takahashi, K., Wilke, C., Woo, K., Yutani, H. and Dunnington, D. (2021). dplyr: A grammar of data manipulation. R package, version 1.0.5.

Wickham, H., François, W., Henry L. and Müller, K. (2020). ggplot2: Create elegant data visualisations using the grammar of graphics. R package, version 3.3.3.

Xie, Y. (2021). knitr: A general-purpose package for dynamic report generation in R. R package, version 1.33.

Xie, Y., Dervieux, C., and Hill, A. P. (2021a). blogdown: Create blogs and websites with R Markdown. R package, version 1.3.

Xie, Y., Thomas, A., and Hill, A. P. (2021b). blogdown: Creating Websites with R Markdown. Open access at https://bookdown.org/yihui/blogdown.