Reading time: 4 minute(s) @ 200 WPM.
I am a huge fan of R and RStudio, especially relative to their use in creating reproducible research (see RStudio as a Research and Writing Platform). I was thus thrilled to learn that a new R package, blogdown, was being developed for producing websites from R Markdown files using RStudio and the static website generator, Hugo.
This website was built and is maintained using
blogdown and Hugo running inside of RStudio, and is hosted on GitHub Pages. For a long time1 I used WordPress for blogging and for website creation, and more recently Google Sites, but both platforms have their limitations (see, for example, this and this). Both WordPress and Google Sites make it easy to quickly produce beautiful websites, and are excellent tools if you can work within the constraints imposed by their ease-of-use.
blogdown package processes your Markdown source, hands it off to Hugo, which then builds a complete website for uploading to your web hosting service of choice.
In the interest of full disclosure I should note that you can build and maintain a static website using Hugo alone, without the need for RStudio and the R
blogdown package. However,
blogdown lets you write your website using R Markdown, whereas Hugo only understands standard Markdown. So if you already use R and RStudio (and you should), using
blogdown to create your website makes sense, and its power and flexibility might even convince non-R users to consider it.
For more information see the articles Making a Website Using Blogdown, Hugo, and GitHub pages and How to make a GitHub pages blog with RStudio and Hugo. The purpose of this post (yes, we are finally there) is to just mention a couple of things that tripped me up for a while in designing and deploying my own
One is that I misunderstood how the
/static/ folder worked. This is described in excruciating detail in Getting images to work.
A second thing that took me a while to figure out:
After editing your website in RStudio, always delete your old files before rebuilding the site for uploading.
Buried deep within the Hugo documentation is a statement to the effect that, as part of their recommended workflow, you should first delete all old files before building the site anew and uploading it to your web hosting platform. If you edit an existing post or create a new one, Hugo does not automatically rebuild every file in your website. In this site, for example, I have Topics and Tags items in the main menu on the sidebar, which will list all of the topics and tags used in all of the posts, along with a count of how many posts there are of each tag and topic. The HTML files that display this information are NOT automatically revised by Hugo when new material is added to the website. It will do this for your local version of the site, and everything will look fine when you use the blogdown function
serve_site() to display the rendered site in RStudio. But prior to publishing the revised website you must first delete all of your old files, and then run the
build_site() to force Hugo to rebuild your entire site. This will update all of the files like Topics and Tags, ensuring that they contain correct listings of topics and tags from edited or newly-added material.
By default Hugo puts your static website into a folder named
public. You can change the name of the output folder to whatever you want. Just remember to DELETE that output folder every time you need to rebuild your website, and then everything will be in sync when you deploy it to your web hosting service.