Hello, and welcome to my new site, built using Quarto. Here’s why I switched from {distill} and the resources that helped me in the process. I also outline some of the customisations I made and set out plans for future blog posts.
Why Quarto? Why now?
I was very happy with my previous website built using {distill}. Then Quarto was released and it quickly became clear that everything that I loved about working with {distill} was true of Quarto, and then some. As a keen user of a whole suite of packages in the R Markdown ecosystem, I could see the appeal of one coherent system to produce reports, presentations, books and websites. Moreover, Quarto is the natural successor to R Markdown, bringing with it a vast range of improvements, building on what Posit (formerly RStudio) learnt over a decade of developing the latter. When it was made clear that although Posit will maintain {distill}, all future improvements will be to Quarto, I knew it was only a matter of time before I rewrote my website once again (for the fourth time).
I’m finding working with Quarto to be an absolute joy!
Resources
This post is not a guide on how to get a Quarto website up and running and styled. There are already great resources for that. These are the the ones that I found most helpful.
The basics
My first taste of Quarto was Mine Çetinkaya-Rundel’s talk about it at the 2022 Toronto Workshop on Reproducibility.
The official Quarto tutorials taught me the basics.
The official Quarto guide is a treasure trove with the section on websites being, needless to say, most helpful for the development of this site.
These two posts on making the transition from R Markdown/{distill} to Quarto were also extremely useful:
Danielle Navarro on porting a distill blog to Quarto.
Alison Hill’s post on why we don’t talk about Quarto.
Going further
The above resources were enough for me to replicate the website I’d built with {distill}, but as I was putting it together, a couple of excellent posts were published that showed how much customisation was possible, and which massively increased my ambitions for my new site:
Albert Rapp’s ultimate guide to starting a Quarto blog.
Christian Gebhard’s guide on switching to Quarto.
These two posts, in particular, gave me the inspiration and most of the know-how to create my custom home page. They also both contain helpful information on themes and styling.
My customisations AKA how long could this possibly take?
I didn’t think it would take too long to make some tweaks, but the more I worked on the site, the more I wanted to change. I’ve managed, with help, to implement customisations that I haven’t seen or read about elsewhere in relation to Quarto. Getting a basic Quarto site up is relatively straight-forward (in fact, Tom Mock shows how it can be done in just 100 seconds), but extensive customisation, particularly when starting with a rudimentary knowledge of HTML and CSS, turned out to be pretty tricky.
In this section, I’m going to list what I think are the cool features of this site, all of which I had to learn how to implement as I went along. Some of them are Quarto-specific. Others I expect will be fairly standard to those with a more advanced knowledge of front-end web development, but may well also be new to others who, like me, have come to website-building with Quarto from a backgroud in R programming rather than HTML/CSS/JS.
For the sake of brevity, in this post I don’t detail how I achieved these customisations. I just note what I had to learn to implement them. I intend to spin each of the points below into separate tutorial-style blog posts. If you’re interested in seeing how I implemented them in the meantime, you can check out this site’s repo.
Animated CSS logo
My favourite feature of my website is the logo/home link in the top left corner, which is animated on hover.1 To implement this, I had to learn first how to create and style the static version using HTML and CSS and then how to apply the CSS animation. I also had to figure out what HTML I could get away with using in _quarto.yml and the best place in that file to add the code. There were also inconsistencies between browers to contend with. I was inspired to animate my logo by Maya Gans, who helped me a lot with the implementation.
Creating a logo with CSS also made it possible to easily change its appearance in the light and dark modes of the site. Along the way, I also learnt another strategy for using different logo images in light and dark modes, using CSS to overwrite one image file with another, which is useful if a logo doesn’t lend itself to creation in CSS.
CSS grid and bootstrap cards
Speaking of which, creating the custom layout of my homepage, using CSS grid and bootstrap cards, was a challenge. The blog posts by Albert and Christian linked to in the previous section got me a lot of the way there, but I still had to dive deep into the bootstrap documentation to make sure the cards and the links inside them all lined up nicely.
Light and dark mode
I put a lot of thought into the colour scheme for both the light and dark modes of the site, and making sure they complemented each other perfectly. For this, I built on what I’d learnt about colour theory and accessibility when designing a custom syntax highlight scheme for my previous website. I also learnt about Sass and made extensive use of custom Sass variables.
Custom syntax highlighting
Having implemented a custom syntax highlight theme for my {distill} site, and created a function for the {distilltools} package so others could do the same, I had hoped to be able to port that straight over to my Quarto site. Unfortunately, it wasn’t so simple. Although they are both called arrow, there are changes in the implementation of the default syntax highlight scheme for Quarto from how it was implemented in {distill}, and, to make things more awkward, there are also inconsistencies between the light and dark versions of arrow in Quarto. It took me a while to get my head around all that. Modifying my original highlighting theme and creating a complementary theme for the dark mode was finicky.
giscus comments box light/dark toggle
Quarto makes it easy to add giscus comments boxes, and giscus (and in turn Quarto) make it simple to select from a handful of different themes to style those boxes. There are a selection of light and dark themes, and one option to set the default light or dark theme dynamically based on your computer system setting. There was not, however, an obvious way of making the theme of the giscus box change responsively on toggling the light/dark switch. In response to my query, with a lot of back and forth, Sage (the creator of giscus) figured out the JavaScript to make this happen and I figured out how to integrate it into the Quarto site.
I would like to apply custom CSS to the giscus comments box in both light and dark modes, which should be possible. I haven’t yet been able to make it work, though, which appears to be an issue related to hosting on Netlify.
Local fonts and open type font features
Because I’m interested in typography and think that professional fonts are worth paying for, and in order to give my site a distinct appearance, I purchased licenses for Lemon Milk Pro (used for body and header text) and MonoLisa (used for code). Having done so, I then had to learn the CSS/Sass to apply the local font files to the site. I also learnt all about open type font features, and how to turn them on and off using CSS. I needed this to turn off the default coding ligatures in MonoLisa.2
Icon links
As on my {distill} site, I’ve made copious use of the icon_link() function in my {distilltools} package, a handy R function that creates a link, with an icon and some text that, with some additional CSS, can be styled a bit like a button, e.g. the code
distilltools::icon_link(
icon = "github",
text = "site repo",
url = "https://github.com/EllaKaye/ellakaye.co.uk"
)outputs HTML which, with some CSS styling for the icon-link class, renders as the following:
The function still works on a Quarto site, but there’s a lot of set-up that’s different. Unlike {distill}, Quarto doesn’t support Font Awesome out of the box, although there are a couple of options for accessing those icons. Copying over the CSS for the icon-link class from a {distill} site didn’t look right on Quarto, so further tweaks were necessary. There are also differences between {distill} and Quarto on the effect of calling the function in a code block vs inline code, and also different sensitivities to spacing/new lines.
The icon_link() function could do with an update, to include bootstrap icons (which are automatically available in Quarto sites), to update to the latest Font Awesome icons (it currently uses 5.15, whereas the latest release is 6.2) and possibly to add more icon sets.
So, how long did it take?
I took me four months, working intermittently, to put this site together, much longer than I had anticipated when embarking on the project.
Shortly after I finally shared my site, I came across the The Programmers’ Credo. It rang true!
We do these things not because they are easy, but because we thought they were going to be easy.
That said, I consider the fact that it was not easy to be a positive, in that I’ve learnt a lot. And, once I’ve finished the series of blog posts on my new-found knowledge, hopefully you will have too.3
Last updated
2023-03-01 15:41:01 GMT
Details
Session info
Toggle
─ Session info ───────────────────────────────────────────────────────────────
setting value
version R version 4.2.2 (2022-10-31)
os macOS Ventura 13.2.1
system aarch64, darwin20
ui X11
language (EN)
collate en_US.UTF-8
ctype en_US.UTF-8
tz Europe/London
date 2023-03-01
pandoc 2.19.2 @ /Applications/RStudio.app/Contents/Resources/app/quarto/bin/tools/ (via rmarkdown)
quarto 1.3.97 @ /usr/local/bin/quarto
─ Packages ───────────────────────────────────────────────────────────────────
package * version date (UTC) lib source
sessioninfo * 1.2.2 2021-12-06 [2] CRAN (R 4.2.0)
[1] /Users/ellakaye/Rprojs/mine/ellakaye-quarto/renv/library/R-4.2/aarch64-apple-darwin20
[2] /Library/Frameworks/R.framework/Versions/4.2-arm64/Resources/library
──────────────────────────────────────────────────────────────────────────────Footnotes
This works best on a laptop/desktop but there’s a hint of it on a smartphone when the logo is pressed.↩︎
As much as I love coding ligatures when writing code for myself, I prefer not to use them when demonstrating code to others as it’s not then clear what they have to type to replicate it.↩︎
Due to other commitments, I’m highly unlikely to write any further posts before late Febrary 2023. There are several for me to write, so if there are any of the above topics you’re particularly interested in, please comment below and I’ll prioritse accordingly.↩︎
Reuse
Citation
BibTeX citation:
@online{kaye2022,
author = {Kaye, Ella},
title = {Welcome to My {Quarto} Website!},
date = {2022-12-11},
url = {https://ellakaye.co.uk/posts/2022-12-11_welcome-quarto/},
langid = {en}
}
For attribution, please cite this work as:
Kaye, Ella. 2022. “Welcome to My Quarto Website!” December
11, 2022. https://ellakaye.co.uk/posts/2022-12-11_welcome-quarto/.