Suppose you want a nice personal blog for yourself. A place where you can brag about your grand achievements in life - or perhaps just a hobby project to waste your time on instead of doing some actual work? Suppose you want to build it yourself even though you don’t know a thing about HTML, CSS and all that coding shenanigan. Don’t fret, you’re now among friends.
In this guide, I’ll describe how to set up a blog like my own in approx. 1 hour using the R program and the add-on package Blogdown. The guide is intended for (and indeed written by) a novice in the arts of coding webpages. So expectoverly detailed step-by-step instructions and a lot of explanatory screen-dumps.
I won’t (or can’t) give a lot of technical explanations of what’s going on under the hood. For those of you who like to know how any of this actually works. For this, I’ll refer you to the two more competent main sources I have used myself when I made my own website: the guide from the author of the blogdown package and the guide from the author of the Academic theme, which we’ll also use here. Both guides are well-written and I highly recommend you to read them at some point but would personally prefer to read them after I’ve gotten to know the basics of the process - hence the motivation for this guide.
This guide is split into the following sub-chapters:
- Introduction to the programs you’ll need
- Setting up your webpage with R and Blogdown
- Customizing the out-of-the-box webpage theme
- Publishing the webpage using GitHub and Netlify
- Writing post, workflow, etc
- The cherry on top: Your own domain, advanced options for customization, whatevs
Before why start, it might be worthwhile to ask, why anyone would even want to make a website with RStudio? It’s certainly not as intuitive as more well-known methods (Wordpress, Weebly, SquareSpace) and has certain limitations. However, the advantages of using RStudio are considerable and -in my opinion- far outweight the slighty steeper learning curve.
Some key plusses:
- It’s free
- Websites load blazingly fast since it is a static webpage. Without going into technical details, this means that the webpage is pre-generated on your computer and uploadet to the internet where it looks exactly the same to all visitors. A static webpage is not dynamically modified based on cookies, user-logins etc. An example of a dynamic webpage could be Facebook where all users see different content based on user details and complex algorithms even though they all visit the same webpage facebook.com.
- Most importantly, you can insert smart graphs, tables and other cool stuff made in RStudio directly on the website! This makes it easy to include data from your research on your blog. And there are even tools, that can make your graphs responsive and interactive! See cool lots of cool examples here.
A quick random example of some code and the resulting graph:
# Make a graph # example from http://r-statistics.co/Top50-Ggplot2-Visualizations-MasterList-R-Code.html) library(ggplot2) data(mpg, package="ggplot2") theme_set(theme_bw()) # pre-set the bw theme. g <- ggplot(mpg, aes(cty, hwy)) g + geom_jitter(width = .5, size=1) + labs(subtitle="mpg: city vs highway mileage", y="hwy", x="cty", title="Jittered Points")
Don’t worry if you don’t understand the code. Just understand that 1) it’s cool and 2) it gives you a lot of possibilities for your website and a completely new way to present your research online that’s easily updated when new results arrive or changes are made in data. It’s reproducible research. Its all the rage in Nerdland these days.
Setup is quick’n easy: First we install the relevant programs, then we make a basic webpage, at lastly we’ll tweak and customize it a bit before we’ll put it out on the big www.
Before we start, you’ll need to install the programs below. Installation is generally quite straight-forward but if you get stuck, google “install X program on Windows/MacOS/Linux” and select the first Youtube video you’ll find.
Install R. This is the coding language which powers everything we’ll build. The program is ugly and unintuitive as heck but we’ll do something about that soon enough. Select operating system (windows, MacOS or Linux) and chose the base version. Installation is straighforward: Just keep clicking “Next”, “Accept” and “Take my soul”" until it’s done.
Install R Studio. This program is a graphical user-interface (:GUI) that makes it way easier to use the R coding language. There are other GUIs for R but RStudio is the most popular. Download the free open source license version of RStudio Desktop (the Installer not the Zip/Tarballs version) and install with standard settings.
Open R Studio. Hopefully it looks like this and we are ready to continue.
Installing R packages
We’ve installed the base programs. Now we need to install two useful R plugins or packages to use R’s lingo: Hugo and Blogdown.
- Install the packages by typing the following in the console window in RStudio:
install.packages("blogdown") # Install the Blogdown package blogdown::install_hugo() # Install Hugo package using built-in function in Blogdown
RStudio might ask you to download some extra packages (like Knitr) that Blogdown or Hugo are dependent on. If so, just follow the instructions and install them all.
The two packages are plugins written by R users that will enable R and RStudio to create our soon-to-be awesome webpage. Hugo creates the static webpage with menus, themes, blog post etc. The purpose of the Blogdown package is to enable the previously smart content on the webpage in so-called RMarkdown files.
Now lets get that webpage on a roll.
Setting up webpage
First we’ll setup a webpage from a pre-made theme, then we’ll customize it.
Close and restart RStudio after you installed the packages.
Make a new blogdown project as shown below.
Select the name of the website folder and where you want to store the data on your computer. For backup purposes I use a folder within my Dropbox but you can put anywhere you want. As you might’ve noticed I changed the Hugo theme from the default to the Academic theme, which I prefer.
For this guide, I’ll assume you’ve also chosen the Academic theme but you can find a ton of other themes on the Hugo Themes webpage.
- When you’ve chosen your theme, press Create project, wait a moment and the RStudio window should look like this:
You’ll notice a new open document called “config.toml” to the left and some new folders and files in the lower right corner, that R and has created in the project folder, you just specified. Basically, the project folders contain all the files (theme, posts, pictures, etc) necessary to create a website. Lets see it!
- Click on Addins and Serve Site:
In the lower right corner, you’ll see RStudio open the Viewer panel and show you your brand new webpage! Okay, its just a built-in example of the Academic theme and it’s still just located in a folder on your computer and displayed in R’s built-in browser.. We’ll get there.
But what happened? The “Serve site” function created a folder named “public” which basically contains a complete ready-to-publish website based on the other files and folders in the project folder. Change the files and folders and you’ll change the webpage. A quick overview of some key files and folder you’ll need to know about, before we’ll start tinkering with ’em:
- config.toml file: Defines general settings of the webpage and the appearance of the Academic theme including name, contact information, theme color, font etc.
- themes folder: The design manual of the website as it is intended by the creator of the Academic theme. The recipe of website if you will. Don’t change these files as it could easily crash the website. If you are feeling adventurous, you should read this overview of HTML and CSS by the creator of the blogdown package and this short description on changing the Academic theme by the theme’s creator.
- content folder: Holds all pages, subpages, blog posts, widgets etc. The content of the website, as you’ve might have guessed from the name.
- static folder: The folder where you put all pictures, downloadable PDF files, etc that you’ll include on your webpage and in your blog posts.
- public folder: the publishable website created by the “serve site” function. If the links on the website stops working after you’ve made changes, try to delete this folder and press serve site again. Otherwise we dont really care about this folder, as Hugo and Blogdown take care of it for us. Don’t add or change files in the public folder as changes risk being overwritten or deleted.
With that out of the way, it’s time to …
We’ll need to do some modifications on the template to customize it to your data and your needs. First we’ll change the name of the website and some basic settings, then we’ll remove what I consider to be clutter and lastly we’ll make a separate subpage for your CV, achievements in life or ranking in Counter Strike perhaps.
As mentioned, the overall settings of the theme are changed in the config.toml file. This file already contains a lot of code and descriptions, since we ticked the “Add the example site of the the theme”-box when we started the new blogdown project during 7). Now we can simply change the premade code to our liking, which is way easier than writing it from scratch.
We’ll start from the top:
- Change the title, the baseurl (address of webpage) and copyright to what you prefer. Right url should be of the form https://YOURADDRESS.netlify.com but we can change it later.
# The URL of your website. # End your URL with a `/` trailing slash, e.g. `https://example.com/`. baseurl = "https://mighty-rick.netlify.com" # Title of your site title = "Rick's Mighty R Blog" # Your copyright notice - appears in site footer. # To display a copyright symbol, type `©`. copyright = "Rick © 2018"
Remember the " before and after what you write, as this tells R, that you are writing text instead of some weird function.
- Save the config.toml file. You should see the Viewer window in the lower left corner disappear and then reappear with your new title at the top and the copyright information in the bottom.
Using the same approach you can also change your name, job title, organization, email etc. in the config file under the headline [params].
- Change the Social buttons of the “biography”-widget at the top.
Near the bottom of the file, you’ll find some repeated code chunks under the headline [[params.social]]. This code decides what link to open, when a visitor clicks on the social buttons at the “biography”-widget at the top of the page: You can remove a button if you dont want it by simply deleting the text. If you more buttons simply copy/paste the text and insert the relevant link and chose an icon. You can choose icons from either Font Awesome or Academic Icons by either specifying icon_pack to be “fa” or “ai” and the provide the name of the icon.
Here I changed the email address, removed twitter and changed the remaining two logos:
[[params.social]] icon = "envelope" icon_pack = "fa" link = "mailto:firstname.lastname@example.org" [[params.social]] icon = "orcid" icon_pack = "ai" link = "https://orcid.org/0000-0002-0035-1914" [[params.social]] icon = "shopping-cart" icon_pack = "fa" link = "https://www.amazon.com/slp/rick-and-morty-merchandise/75eks9xvvajgcvx"
To be continued..