Welcome to my Quarto website!

Resources I found inspiring and useful when building my new site, plus notes on my customisations

Quarto
distilltools
Author

Ella Kaye

Published

December 11, 2022

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:

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:

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.

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

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

  1. This works best on a laptop/desktop but there’s a hint of it on a smartphone when the logo is pressed.↩︎

  2. 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.↩︎

  3. 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/.