How I Deploy My Website to GitHub Using RStudio, blogdown, and Hugo

Simplify, simplify.

Web Technology
R / RStudio / GitHub

Reading time: 3 minute(s) @ 200 WPM.

I have worked for days trying to get this website up and running on GitHub Pages. I think I finally have gotten it to work.

This is that story.

I have studied the following sources of punditage:

All of the articles and discussions were enlightening, and helped me arrive at what I believe to be the simplest way to deploy a Hugo-generated website on GitHub Pages, at least for me.

I have one GitHub repository for this website, richardlent.github.io, under GitHub Pages. I have an RStudio project in a local working folder of the same name, maintained on Dropbox. That folder was cloned from my remote GitHub repository, namely richardlent.github.io. So when I revise the website, using blogdown and RStudio, Hugo writes the static site files to the root of that folder. To accomplish this, I have the line:

publishDir = "../richardlent.github.io"

in my config.toml file. This overrides Hugo’s default output folder, /public/.

Before I rebuild a newly-revised website for pushing up to GitHub, I first purge my working folder of all files and folders previously generated by Hugo, because, as Hugo hath spake:

Running hugo does not remove generated files before building. This means that you should delete your public/ directory (or the directory you specified with -d/–destination) before running the hugo command, or you run the risk of the wrong files (e.g. drafts and/or future posts) being left in the generated site.

Because I have Hugo write its website files to the root of my working folder, richardlent.github.io, instead of to a /public/ folder, it’s a little more work for me to purge old files. Instead of simply deleting the /public/ folder, I have to manually go through my project’s directory tree, deleting everything except the core Hugo file structure. In particular, I am careful NOT to delete the /content/, /static/, and /themes/ directories, which contain the source materials used by Hugo to build the website. Also, I have a directory called /datasets/ that contains various data files used in various posts. That directory is always left up on GitHub and never deleted, only updated, because deleting it would break vital connections and cause .Rmd files that use those datasets to fail to render. I also do not want the contents of those directories to be pushed to GitHub. My .gitignore file helps accomplish this:

.gitignore:

.Rproj.user
.Rhistory
.RData
.Ruserdata
.gitignore
.gitkeep
/**/*.Rmd
config.toml
richardlent.github.io.Rproj
content/
static/
themes/

Here are some critical fragments of my config.toml file:

baseurl = "https://richardlent.github.io/"
canonifyurls = true
relativeURLs = true
publishDir = "../richardlent.github.io"

The above settings were arrived at by a combination of reading the articles referenced above plus a massive amount of trial and error.

And so here is my procedure for revising this website using RStudio:

  1. After adding new material via R Markdown files, and verifying that the site is working locally using the blogdown::serve_site() function, I terminate the local server and delete all Hugo-generated files from my working directory (richardlent.github.io).

  2. Using the git version control tool built into RStudio, I commit the file deletions to the local repository and then push the file deletions to my remote richardlent.github.io repository. (Thus my website is briefly unavailable.)

  3. I then rebuild the site using blogdown’s build_site() function.

  4. The newly-created website files are then committed to my local git repository and then pushed to GitHub. The revised site is now live.

At least, I hope it is.

 Share!

 
comments powered by Disqus