Migration from Hugo/blogdown/Wowchemy to Quarto
Motivation
Like many folks who use R, RMarkdown and related products a lot, I was excited about the blogdown package and used it to build my website with Hugo. Also as many did, I used the Wowchemy (back then called Academic) theme. I wrote about that setup here.
The results were nice, but both Hugo and Wowchemy kept changing all the time and stuff kept breaking. It wasn’t robust, it got rather complex and fiddly, etc. I started dreading making changes to the website. Enter Quarto. I first watched from the sidelines thinking that my current setup was ok and I didn’t need to change (yet). But after a few online presentations, I was convinced that Quarto was the new way forward and would in the long run provide a much better experience.
I therefore decided to tackle the website conversion project. I had a lot of help from others who already did this (I’ll provide links below).
I wanted the new website to be as close in content/functionality as the old website. Since I didn’t have 100s of pages to convert, I was ok doing some manual adjustments. Here is a brief summary of what I did and some pointers to a few things I learned that might help others.
Who this is (not) for
This most directly targets folks who want to switch from blogdown/Hugo to Quarto. I’m hosting things on Netlify, but it should work for other hosting platforms too. Some of the tips might also be useful for folks who plan to build a Quarto website from scratch.
This is not a detailed walk-through. For that, see the Quarto documentation or for instance this blog post. I’ll describe a lot of steps only briefly, and make comments on some topics that might be not yet commonly known.
Setting up the website
I started by creating a new Quarto website. Either the Quarto documentation or these blog posts by Danielle Navarro and Albert Rapp worked well.
For the main page, I simply used the about page template that is built into Quarto. (While my about.qmd page is just a regular page.)
I structured the new website to be as similar to my old as possible. For me, that meant folders and subfolders for posts, presentations and projects, and all other files (e.g. about.qmd) in the top level.
Note that while I have posts and presentations separately, and under the old setup those pages were somewhat different, with Quarto there is (currently) no separate styling for presentations, thus it is basically another collection of posts. Only in this case, each post just contains the basic information of the presentation and a link to the slides and other relevant material. The same is true for the projects, they follow again the same structure as the posts, just somewhat differently formatted.
It would be possible to tune more, and make the presentations entries display differently. But I wanted to keep it simple, I learned that too much customization is just a time suck for me 😁.
For the projects, I made a change. They are also set up like posts, but I wanted the image that’s shown as thumbnail to also show on each page explaining a project. That was the way it was on my old site. I was thinking of messing with the project pages, but realized I could just use one of the ‘about’ page layout templates and that would do the trick. So I just added the solona template into the YAML of each file and got a layout that looked good enough for what I wanted.
Configuring the site
The main file for setting configurations is the _quarto.yml file. Additional configurations can be done in _metadata.yml inside the posts and presentations folders. I followed a mix of the Quarto documentation and the blog posts mentioned above and below to configure those files. You can check out my setup on the GitHub repo of this page.
Converting YAML sections
I had to do a bunch of manual conversions of all the index.qmd files that go with each post and presentation. It was a bit tedious but not too bad. Basically, I had to remove anything from the YAML that was specific for Hugo/Wowchemy and format it to have the fields supported by Quarto. I found Danielle’s post to be helpful for a quick orientation. (Note that she converts from Distill, so her starting point is slightly different, but the new Quarto entries are the same.)
Setting up a 404/not found page
This is not really required, but I liked this approach from Lucy D’Agostino McGowan and decided to mostly copy it and adjust a bit for my purposes.
Turning on comments
I used utterances before to allow folks to comment on certain sites. This can be done easily as explained in this Quarto documentation section. To prevent comments on certain pages, one can turn those off in the YAML, also also described on the Quarto documentation page. An alternative is to place the utterances information into the _metadata.yml files, which then means comments are only on for those specific files/folders, in my case the blog posts and the presentations.
HTML form embedding
Update 2023-01-09: At the end of 2022, I decided to stop doing my newsletter for the time being and turned off the newsletter subscription section. Leaving this here since it might still be of general interest to figure out how to embed HTML.
For my newsletter subscription page, I embed HTML code produced by Mailchimp. It took me a little bit to figure out how to do it. This tip explained it, basically the setup looks like this:
```{=html}
ALL THE HTML STUFF FROM MAILCHIMP GOES HERE
```Redirects 1
My previous website used slug: labels in the YAML to provide shortened URLs. I wanted to keep those old URLs so breaking links are minimized. First I was thinking of following this example by Danielle Navarro and adjusting the code such that it parses the YAML of all my index.qmd files, pulls out the slug part and builds the paths and redirect table. It should have worked for me since I’m also hosting this website on Netlify, like Danielle.
But then I found a simpler option, using the aliases: setting, here is a an explanation/example. I tried to do an automated search and replace, but it didn’t quite work, so I ended up doing it manually. I basically replaced this:
slug: publications-analysis-1with this:
aliases:
- ../publications-analysis-1/in the YAML of all my posts (my presentations didn’t use slugs).
Note on this: I ran into some problems initially. Since I was mapping into the same file structure, just a different file name, I wrote this:
aliases:
- publications-analysis-1That didn’t work. On contemplation, the alias is referenced to the current document. So if my file is https://www.andreashandel.com/posts/2020-02-01-publications-analysis-1/ I need to move up a folder and place the alias folder/file publications-analysis-1 there. That was confusing on first try. I only figured it out once I looked into the _site folder to see what Quarto was producing, and from that deduced the right setup.
Redirects 2
After I got the aliases bit to work, I realized that I needd further redirects. On my old blog, I had andreashandel.com/talk redirect to andreashandel.com/presentations. The first URL is on many of my presentation slides and I didn’t want to change them all. So I figured I should use Danielle’s approach after all, and make a small _redirects file that contained these. Basically it looks like this:
/talk /presentations
/talks /presentations
/post /postsI followed her instructions of placing this bit of code into the main index.qmd file.
Update 2023-07-06: I noticed that sometimes when I build the website, the whole _site folder gets erased and rebuilt (which also deletes the _redirects file). But the index.qmd file might not get re-executed since I’m using the execute: freeze option in my _quarto.yml file to prevent running everything each time. This means the code snippet inside index.qmd which makes the _redirects file isn’t run. The solution I found was to use Quarto’s Post-render functionality. Basically I placed the few lines of code that I got from Danielle’s example into a separate makeredirects.R script and added that to the main _quarto.yml file as
project:
post-render:
- makeredirects.RIt now runs each time after the rendering and produces the needed redirect file.
Widgets
On my previous website, I had several sections (widgets) on the main page under the static welcome text. Those showed my Twitter feed and most recent posts and presentations. I was trying to see if I can reproduce that with Quarto. Based on this example it seems one could do something like that. I contemplated giving it a try. But then I decided to keep it simple, and let interested readers klick on my Twitter/Posts/Presentations sections if they want. No need to complicate things 😁.
Extensions
To get the nice icons in the footer that Andrew has, one needs to install an extension. In this case, it’s the fontawsome extension. This is easily done, as described here. or here. I expect many more cool extensions to show up soon.
Other settings
I’m using Google Analytics, it is easy to include that in a Quarto website. I also turned on the Cookies setting notification (I don’t use any cookies directly, but Google Analytics likely does, and probably Mailchimp that I use for my newsletter too?).
Publishing
I host my website on Netlify. I followed the Quarto documentation. First I did a quarto publish netlify. That placed my website onto Netlify and gave it a temporary URL. That was great for testing it online (as opposed to testing locally with Quarto’s preview option, which of course I used a lot as well). Once online, I ran a link checker (I like using Dr Link Check but there are many others.) Of course there were broken internal links, so I went ahead and fixed them. I decided that I like the somewhat manual publishing of the site instead of doing it automatically with GitHub integration (also an option described in the Quarto documentation, and what I was using). The manual approach means I can mess around with new blog posts and sync with GitHub and don’t have to worry about using the main branch or not and then only once things look good do I publish with Quarto. So I changed my setup to that. That was done easily by setting the information in the _publish.yml file to point to my actual website URL, and changing the settings on the Netlify side as described in the Quarto documentation.
Summary
Overall, it wasn’t too hard. The one item that got me stuck for a bit was the aliases issue as described above. The conversion did require some manual changing, which I’m sure I could have written R scripts for it, but since my webpage isn’t that large, it seemed easier to just do things by hand. The new site is slightly different, some parts are simplified, but I got pretty much the same functionality and content back. And it is a much simpler setup compared to the - in my opinion - fairly convoluted setup of Hugo/blogdown/Wowchemy. Overall I’m happy with the results. My research group website is still using blogdown/Hugo/Wowchemy. That one has a few more custom layout features, which would likely require some fiddling before they work in Quarto. However, I have high hopes for those extensions and I’m pretty sure soon someone will have made new layouts, and then I might just be able to use some of them. So research group website conversion will happen, though probably not this year 😄.
Further resources
In addition to the main Quarto website and the blogs mentioned above, the a Quarto tip a day by Mine Çetinkaya-Rundel and Thomas Mock’s materials (look for his Quarto training repositories) are great resources. This repo has materials for one of his workshops, here is another one. This tutorial by Isabella Velásquez is another nice resource describing specifically Quarto blogs.
Acknowledgments
It should be obvious that I owe a lot of these ideas to the blog posts and other resources I cite above. So thanks to those who tried it before me and wrote about it!