Notes on Converting from Blogdown/Hugo to Quarto
Fun With Quarto
During the course of this blog since the first post in 2016, I have written entries each time I have made a major change in how the blog was created. In 2018 I connected Netlify to the Github Pages version of the blog and acquired the name johngoldin.com via Netlify. In 2021 I converted to the Hugo theme apéro which allowed for a considerable reorganization of the blog and a better appearance that involved much more use of images. I should thank Alison Hill for creating apéro and nudging me to inject a bit more life into my blog. And then along came Quarto.
I have written a couple of posts that used Quarto rather than Rmd. Quarto has been easy to pickup and blogdown/Hugo always had a lot of disadvantages. During my Hugo/blogdown period I was always confused about whether to use .md, .Rmd, or .Rmarkdown. I was always frustrated by the RMarkdown features that were out of reach because I needed to be compatible with Hugo. One of the big things I missed was code-folding. Anyway, after RConf 2022 I felt an irresistible pull to convert my blog to Quarto.
I started on August 16th, and as I write this it is September 12th and I just switched johngoldin.com to point to the Quarto version.1 I think it’s basically in good shape. I’m still checking on Hugo shortcodes (usually figures) that haven’t converted. I have made an effort to organize things so that the old URLs may still work, but one last step will be to fill in some more aliases in the YAML and maybe add some redirects to my Netlify setup.
The examples in the Quarto Gallery have been a great help. In general the Quarto documentation has been a big help. As usual when I started out it took at lot of reading and re-reading the documentation and examples to understand a few core things. The crucial step for me was to understand Document Listings. Once I got that straightened out, I was on my way. I had a surprising amount of difficulty figuring out how to set the image that accompanies the post reference on the listing page. I didn’t realize right away that depends on the “image” item in the YAML at the start of each post.
Because I don’t have much in the way of actual readership, it’s easy for me to make huge changes in the blog without fear of disturbing anyone.
The sections that follow are really just notes I accumulated while I figured out how to do the conversion.
Examples
I’m collecting examples of blog sites done in quarto.
Robert Mitchell describes moving to quarto blog
Examples from Quarto gallery Bea Miller example of a series.
Gotchas
I noticed an interesting difference in handling of images. I had a post that had two similar images. In the finder, each showed a size of 2560x1920. For the first image I inserted it into the post using raw html:
<img src="img/john-weight.png" alt="Plot showing daily weight with periods during use of LoseIt to count calories hightlighted in yellow."/>
For the second image, I used markdown syntax:
{alt="Plot showing daily weight with periods during use of LoseIt to count calories hightlighted in yellow."}
When I rendered the Rmd/Blogdown/Hugo version the two images appeared the same in the browser. But when I rendered them using the quarto, the first image (using html img) was way too big. I changed the first image to also used markdown syntax and it looked fine. I imagine this has something to do with scaling the image and maybe appears on a mac. Or actually I should acknowledge that I don’t know what caused this. The moral of the story for me is that with quarto maybe it’s safer for me to use markdown syntax rather than raw html because they may have thought about issues I’m not even aware of.
In the quarto version when I use markdown syntax to insert the image, in the html it ends up as class=img-fluid (which is a Bootstrap css class). In the html created using blogdown rendering the Rmd file, no class is applied. Maybe there is other setup html in the blogdown version that interacts with the Mac retina resolution and cuts down the photo. One can see that I’m trying to discuss something that I don’t know enough about to fully explain or understand.
Customizing Your Blog
Albert Rapp has a lot of concrete information about setting up a Quarto blog, but also how to do some customization. He has some very specific suggestion on use the renv package to preserve the package environment for each blog post.
Hugo “slug” Yaml
In blogdown/hugo I made extensive use of the “slug” item in yaml to simplify the eventual URL for a blog entry. For example, routinely I’d use the year and month rather than year and month and day. Plus I sometimes shortened long folder names. Quarto knows to use slug if the type is Hugo, but it doesn’t seem to use slugs if you publish from Quarto directly. This is not a big problem, but it means that I may want to add an alias to each post or maybe start using “redirects” in Netlify.
I already have a bunch of aliases from when I converted to the Apéro theme in Hugo.
This reminds me that it’s a big advantage that I don’t have a big audience for my blog. It means there is less pressure to nail down every detail. But I will need to think about the small number of places where I have published URL’s to make sure they will still work. The most important is the information entry for my talk at RConf2022, and I just verified that one correctly points to my Quarto site.
Another YAML item: In Hugo/blogdown, I can have the draft item and set it to false. In Quarto it seems that if the “draft” item is present, the post will not be included regardless of whether it is set to true or false.
Putting Images in the Margin
I took the trouble of re-working my items on Walking in Britain to use the class .column-margin. I think it makes the text flow much better. I am quite ignorant of CSS and related HTML so working on some of the details of the formatting has pushed me to get a little bit better understanding of how things like CSS classes work.
Why Do I Like Quarto?
My overall impression of Quarto is very positive. It’s surprising because so much of Quarto seems to be an extension of RMarkdown. As an RMarkdown user, I had no difficulty getting started with basic editing.
The quality and quantity of documentation provides a lot of support. The Gallery was a great help as well.
The default appearance of my site is clean and classy. Things look good and that makes me feel good.
Now that I am getting the hang of things, I can control the organization of the main menus. It’s more flexible than the constraints of Hugo and a Hugo theme.
It is easy to use
quarto publishto simply and directly publish my site to Netlify. It works better, I think, to not have publication directly linked to my github. When I was doing daily COVID updates from Connecticut data I didn’t need to have all those updates in Github.It’s early days yet in the life of Quarto and I’m confident there will be a lot of helpful and useful extensions and templates. It’s good enough for me as it is, but it’s also going to get even better.
I am able to use the full power of Quarto for my web site documents but also use the same techniques for other standalone documents. I don’t have the confusion of multiple formats that complicated using RMarkdown.
What’s the State of My Blog Now?
For two years I was updating Connecticut COVID stats every weekday. At the end of June the Department of Public Health changed the format of some tables. I haven’t kept up with those changes so my COVID updates have not been in good shape. Plus other things have been going on that make the format less useful. Home testing makes the case counts difficult to interpret. On my regular tabulations I wasn’t even tracking vaccinations. And vaccinations have become more problematic to track. For about a year everyone was using the concept of “fully vaccinated” for the first two Moderna or Pfizer shots. Yesterday I received my third booster. Increasingly we will need to talk in terms of who is “up to date” on their COVID vaccinations rather than simply count how many shots they have received. The end result is that right now I’m not doing anything regularly on tracking Connecticut COVID.
Footnotes
I had difficulties with Netlify. Generally Netlify seems to make things easy for a casual user like me, but in this case I was a bit confused. My domain name is registered through Netlify so that should make it easy. I was hoping there would be a straightforward way to switch which site was pointed to by my domain name. Their instructions were oriented toward people who had domain names registered through other services. I had to delete my old domain records and then go through the process of adding a domain. Unfortunately I didn’t keep good notes on exactly what I did. I was a bit confused. Anyway, it seems to be working correctly.↩︎