Building a website in RStudio using Hugo and Netlify
After running on various versions of home-brew software and Wordpress, I got fed up trying to force PHP and MySQL into behaving and transitioned my website over to Jekyll running on Netlify. However Jekyll isn’t the most userfriendly of software, and trying to make Ruby run properly every time I updated macOS was putting me off writing because I’d then spend a day trying to publish it!
Recently I’ve been inspired by fellow anaesthetist Chris Tomlinson’s use of Hugo and Github pages to run a static website, and as an R-zealot the fact I can run it entirely from within the One True IDE RStudio had me sold. So with a few modifications and updates to his installation instructions here is how I got this site running on Netlify using Wowchemy’s Academic template…
Step 1: Install Hugo
First step is to install Hugo and its dependencies. Specific instructions by OS can be found here, but on macOS you’ll need to start with Homebrew (you mean you haven’t already got it?), updating it, and installing Hugo and required dependencies:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew update && brew upgrade
brew install git golang hugo
Next step is to update .zshrc
(or .bashrc
) to point Hugo at Go by running nano ~/.zshrc
and adding the line:
export PATH=$PATH:/usr/local/go/bin
Step 2: GitHub
If you don’t already have one, register for a GitHub account. You don’t need to know Git, but if you want a quick exploratory tutorial the Software Carpentary tutorial is a good start, and the GitHub desktop app is a good cheat to avoid terminal errors.
When you’re ready fork the Hugo Academic template into your own repository https://github.com/YOURUSERNAME/starter-academic
.
Step 3: RStudio
Create a new project in RStudio from your forked template by selecting File > New Project… > Version Control > Git. Use your fork of the starter project URL and select where you want it saved (a good place to save it is the ~/Documents/GitHub
folder that GitHub desktop uses). Then hit Create Project, and wait while it downloads all the files.
This will open a new project based on all the included academic.Rproj
file, and open the file structure of the template in the RStudio Files pane.
You also need to install Blogdown to allow R to run Hugo, and include it in the environment, by running in the console:
install.packages("blogdown")
library(blogdown)
To run the website, use blogdown:::serve_site()
. It will appear in the Viewer pane, but renders more accurately if you visit the URL that blogdown outputs to the Console (eg Serving the directory . at http://127.0.0.1:4321
) using Chrome/Safari/etc.
Step 4: Netlify
Login to Netlify using your GitHub credentials. Fill in the registration details and you’ll be taken to your “Team Overview” (yes, you’re a team of one). Under the “YOURNAME’s team” box is “Sites”, so select the green “New site from Git” button, which allows you to automatically process your GitHub repository and publish it as a website:
- Connect to GitHub for continuous deployment (it may reauthenticate)
- Select the repository
YOURNAME/starter-academic
. - You’ll get a number of build options. Owner should remain you, branch to deploy should be master, and under “Basic build settings” the build command should be
hugo --gc --minify -b $URL
and the publish directory set topublic
.
Hit deploy site, wait for it to build, and you should be rewarded with a lovely website (with a big green top telling you to edit it). It’ll probably have a stupid name like lemon-upside-fish.netlify.app
but it’s trvially easy to change this to something meaningful, or even link it to a domain name you own.
Step 5: Edit and update your site
Hugo uses fairly human readable Markdown so writing new content and building an elegant website is relatively straightforward. You can open the files directly from the Files pane, edit them in RStudio, and when you hit save it should automagically update in your browser. Have a play using the Wowchemy documentation and make it lovely and pretty.
Now for the magic. Netlify will watch for updates to the Git repository and run Hugo automatically to publish the site. All you have to do is push the updates to GitHub, either by cheating and using the Desktop app, or by switching to the Terminal within RStudio and executing:
git add .
git commit -m "Write a comment about it here"
git push -u origin master
Enter your username and password, and Netlify will perform witchcraft in the background and publish your site.