R
for required packages:install.packages("pacman")
pacman::p_load(knitr, rmarkdown, bookdown, data.table, sjPlot, car)
pacman::p_load_gh('rstudio/blogdown')
By the end of this workshop you should:
None of this would be possible without these trailblazers and the open source community
Focus on the stats, code, interpretation. Leave everything else (filling in tables, inserting plots, formatting) to the typesetter.
Pictured above is Adam Smith, author of The Wealth of Nations (1776), in which he conceptualizes the notion of the division of labour.
Markdown is to HTML what LaTeX is to TeX
Markdown was initially created by John Gruber as a simple way for non-programming types to write in an easy-to-read format that could be converted directly into HTML.
See the Markdown cheatsheet for syntax details.
Note: All HTML is valid Markdown. If you’re stuck not able to format your content how you would like you can always use plain HTML instead of Markdown (e.g. use <br>
for line breaks).
R Markdown combines the computing power of R with the simplicity of Mardown syntax to generate high quality reproducible reports in various formats.
See the R Markdown cheatsheet for syntax details.
We first start with a minimal, complete, and verifiable example (MCVE) to ensure you have all the correct dependencies and updated versions of software installed. In Rstudio, create a new R Markdown document:
Select Document
and ensure that the default output format is HTML
. Enter a title if you wish, but you can change this later. Click on OK
:
A default skeleton of R Markdown code is included everytime you create a new R Markdown document within RStudio. The important pieces of the document are highlited in the figure below. The YAML
header is very similar to the header in LaTeX; it contains all the options for the document. The two mandatory pieces in the YAML
are a title and the output format. See here for further customizations.
Leave the content as is and click on the knit
button:
This will prompt you to save the file:
An RStudio window of the compiled HTML
file should appear
The following figure shows exactly what happens when you press the Knit
button. The .Rmd
file is first converted into a markdown (.md
) file, which is subsequently converted by a tool called pandoc into the format specified by output:
in the YAML
:
Even until a couple of years ago, creating a website along with a blog that embeded both code and text, required specific knowledge of HTML
. Tools such as markdown
and R Markdown
, have abstracted the difficult part of writing HTML
code for us, so that we can focus on content and creating reproducible analyses. Building on these very tools, the blogdown
package by Yihue Xie
has made it that much easier to create websites that allow you to showcase your scripts, code and reports, while also maintaining a public portfolio, i.e., having an online presence.
In this part, we will create a minimal working example of a blogdown
website. I have provided detailed screenshots with annotations of each step. In general a red encircled annotation means you should click on it, and a red rectangular annotation means that you should verify or be aware of this. Note: the screenshots provided here are from a Linux operating system, however it will be similar on a Windows or Mac.
We first need to create two GitHub repositories (abbreviated as repo). One will hold the source code for your website, and the other will host the compiled HTML
files which make up your website (these are often referred to as static files). Head over to your GitHub account online and create a new repository:
Give it a name. It can be anything you want such as website
, website_source
, source
(just pick a name that will remind you that this repository contains the source files of your website). In the screenshots below I used website
throughout. Check the box to initialize the repository with a README and then click on Create repository
:
You should now see the homepage of your repository. Note the URL for the repository is given by https://github.com/<user-name>/<repo-name>
. This online version of this repo is called the remote
.
Click on the Clone or download
green button and copy the URL to your clipboard:
We now want a local
copy of the website
repo so that we can start creating content to put on our website. Head over to RStudio and go to File --> New Project..
:
Select Version Control
:
Then select Git
:
Paste the repository URL that you copied from your remote
GitHub repo. Enter a project directory name (I call it the same as the repo name), and if you want, copy the files of the remote
repo to a specific subdirectory:
You will notice that a .Rproj
file was created and a .gitignore
file was created. Let’s first test to see if our connection from the local
repo to the remote
repo is working. We first check the boxes next to each file and click on commit
:
Enter a commit message and click on Commit
:
If everything went ok, you should see a window like this:
Next we want to Push
these local changes to the remote
. Click on the Push
button:
This will prompt you to enter your GitHub username:
… and password:
If everything worked smoothly, you should see a window like this:
Head over to the webpage for your GitHub repo (refresh the page if necessary) and you should see you commit message, as well as a .gitignore
file and a .Rproj
file.
We now need to repeat the exact same steps as before to create the second repo which will host the static files for your website. Create a local copy, though it is not yet necessary to push your changes to the remote
as this will be done in a later step.
Note: the name of this repo must be <user-name>.github.io
.
Note for Mac Users: the first time you install Hugo, you might need to install homebrew.
Choose a theme from https://themes.gohugo.io/ and find the link to the theme’s GitHub repository. In this example we choose the Academic theme.