The making of

Acceptance

I was due for making another work website, and I started with the most obvious option — I made a Wordpress site on my school’s hosting platform. I dropped in the same basic content found here, a short bio for the landing page, and a lightly formatted CV. I chose a theme and modified the style using the Wordpress GUI editor. My institution uses a limited and out-of-date Wordpress installation, but I didn’t need much. The result was totally fine. It gave me a place to work out what I was going for.

I thought about including a section of the site for notebooks like this one. Keeping the rest of the content on Wordpress and adding HTML output from Rmarkdown would have required several intermediate steps and I wasn’t sure how well they’d work. I’ve seen other R developers (Alison Hill, Amber Thomas) use Hugo and GitHub Pages as a publishing solution for Rmarkdown, and I looked into it again, the moment I had my Wordpress page in publishable, if not launchable, condition.

I last used a static site generator almost ten years ago, at a time when most of the tech that goes into them was fairly new, and my project of creating a simple personal site (like this one) with nothing but a text editor and a command line required Git, CSS, Ruby, and at least two other markup languages. At every step I tore down whatever template I had to work with and re-wrote it line for line so the code looked exactly how I wanted it and contained nothing I didn’t use. I came away from the experience never wanting to do that again, and now all of it is back, better than before, and it only took me one night to get from zero to finished Wordpress site to finished Hugo + GitHub Pages. That’s Phase One.

Step zero: Existing environment

A probably incomplete list of everything already installed and initialized:

• macOS and Terminal
• GitHub account and working connection between GitHub.app and CLI
• Homebrew to install Hugo
• Atom and RStudio for editing

Step one: Set up Hugo

I relied on the official Hugo documentation for setup. I think it’s best to have Hugo installed and working locally before integrating with GitHub or another host, or starting with the purely RStudio route, although I can see that working just as well. The tools I used in these steps were primarily Terminal to run Hugo commands, Finder and Atom to move and edit files in the Hugo site folder, and Firefox to view the local site.

The subtasks in Hugo setup are:

• Initialize a site in a new folder
• Install a theme and create some content (I pasted from Wordpress)
• Confirm functionality on local server and adjust style and templates
• Confirm build success (check whether index.html in /public folder looks right)

The last piece became a sticking point for me. It is a somewhat common problem for CSS to be missing from the Hugo build output, at first. Because I recognized that the first theme I chose was using SCSS, I thought the odds were good that my version of this problem involved a CSS processing issue, and I did not want to troubleshoot that. I had gotten the site looking the way I wanted with this theme, but I knew it wouldn’t be hard to replicate, so I switched themes to Yihui’s version of the Lithium theme, which I hope will also prevent issues with Rmarkdown publishing. I am using the Sakura CSS framework and was able to easily drop that stylesheet into the Lithium theme. At this stage, all the challenges I encountered were limited to Hugo, and modifying templates and other web code to get the built result I wanted. The advantage of ignoring publishing or setting up an IDE at this stage is that I only ever had to troubleshoot Hugo and the site code.

Step Two: Connect Hugo and GitHub Pages

• Create repository (choose user or project site)
• Create GitHub Page from repo
• Add workflow for publishing public folder
• Test pushing new site builds to GitHub

If I wasn’t interested in using Rmarkdown to publish notebooks to my page, I’d stop here. I could continue to use Hugo in the command line, add new content by writing pages in markdown using Atom or any other editor, and publish to GitHub pages by pushing builds, which is a pretty smooth workflow.

Step One: Set up blogdown in RStudio

The method described in the blogdown documentation starts in RStudio, and effectively replaces all the tools I used in my Phase One. Starting here might save time, but breaking up the process helped me narrow the cause of errors, and understand the order of operations.

Having already installed all the necessary components, adding RStudio to the Hugo publishing procedure went like this:

• Install package and check Hugo version
• Test serving local Hugo site in RStudio viewer (instead of using a browser to view the locally hosted site, it’s available in the RStudio viewer window)
• Use RStudio Addins to create post
• Here is the post!
• Return to Hugo layout files to create Notebooks section of site and set up permalinks
• Test publishing from Rmarkdown builds

This post is a working demonstration of the above. Now, I can use notebooks to share work in progress, although I can’t limit access or allow interaction with the data, yet.

Step Two: Shiny

I’m interested in using Shiny to allow colleagues to interact with my data. There’s a lot to learn about Shiny that is separate from the project of publishing this website. For now, I am using shinyapps.io to host my apps, and referring to the official written tutorials and other sources to develop and deploy my first apps.

Since the apps won’t be part of the Hugo site structure, I can move them into other folders, and have the option to use shinyapps.io directly for sharing interactive data. This represents the extent of a static site generator’s capabilities, so the development cycle now belongs to R and Shiny, and the initial web development phases are complete.