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.
In the olden days, we built websites by writing a bunch of HTML files that were then uploaded to a web server. That was tedious, but it gave you maximum flexibility, at the expense of having to learn the HTML markup language and maybe some programming languages like JavaScript. The attraction of the RStudio + blogdown + Hugo system for web design is that it works within a well-established development environment and doesn’t require that you know HTML. There are many pretty, pretty themes available for instantaneous (well, almost) website creation. And you can use all of the power of R, running inside of RStudio, to produce data analyses and graphics, and then write R Markdown documents (the lightweight syntax of which is much simpler than that of HTML) within that same system to produce a website or blog to communicate your results. Or, you could just use RStudio by itself as a web design platform without needing to know much of R, using the standard Markdown language as a simple way to write your source material. (Please note, therefore, that there is standard Markdown, and then there is R Markdown, a superset of standard Markdown that allows embedded code from R and several other programming languages.) The 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 blogdown-and-Hugo-fueled website.
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 blogdown function 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.
“To a fruit fly researcher . . . a ‘long time’ might mean three or four days. To an archeologist, ‘recently’ might mean three or four centuries.” How Long Is a Long Time, Anyway?↩