What I Like About Quarto So Far
In the last few years since my PhD, I have happily been teaching reproducibility to my students with R Markdown and teaching reproducibly with R Markdown. For the distinction of reproducible teaching and teaching reproducibility see our paper.
This summer I decided to switch to Quarto. Now that I am in the third week of the academic year, I want to make a few comparisons between my old workflow and the current one and share what has worked for me. If you teach/taught (a course, a meetup workshop, etc.) with R Markdown, then this blog post may be useful.
Prior to this academic year, I wrote my course websites (e.g. Introduction to Data Science in Fall 2021) in HTML despite preparing handout, slides, and starter codes all in R Markdown. I learned HTML back in my undergraduate years and always felt comfortable with writing everything from scratch, designing my own CSS templates, etc. When I used R Markdown rendered into HTML or any other default packages whether they are in HTML or Hugo, working with templates was often frustrating since it took me forever to figure out how to change defaults. However, when I teach I often work with multiple TAs. They know how to use R Markdown but not all have the training in HTML.
If written simply, TAs and other members of the teaching team can now understand my course websites since markdown is a lot easier to read than HTML for novices.
Defaults still give me a headache and I still need to figure out how to change defaults but Quarto has much better documentation than R Markdown. Considering that it is new, I expect the documentation to get even better. I did achieve similar aesthetics of my old course website in my new course website.
I fell in love with Quarto variables. Of course, this was also possible in HTML by using JS but I never did and Quarto documentation was really helpful in incorporating this feature. I defined some variables about my course that I use on multiple pages, for instance, the home page has course title and course term all generated from variables. Next time I teach this course, updating the course website will be quite easy. In fact, incorporating a similar structure was also easier for my another course that I am currently teaching.
I have over-used the includes feature which allows another document to be rendered within another document.
I use this a lot in HTML too.
For instance, my CV is a separate HTML document that I can print but it is also nicely embedded on my website.
I use this to distinguish course-specific content and generic content.
For instance, under course policies there is generic content such as letter grades and percentage correspondence that is the same across all our university courses, Disability Services Center information etc. This information is included in the policies.qmd document but anything specific to the course is in a separate .qmd file that is included in the policies.qmd
By far the output-location: column chunk option is MY FAVORITE feature of Quarto. It is extremely helpful for showing code and output in two separate columns. In the past, we would first write the same code twice. The first one would display the code but not the output and the next one would display the output but not the code. We would also have to pull the first code to the left and the output to the right. Now it can all happen in a single chunk.
These are either things that Quarto does not currently support or there is not enough documentation there or simply I am not being smart enough!!!
If you like me, like using Font Awesome icons, the bad news is that Quarto uses Bootstrap icons by default. Good news though, Font Awesome can be installed as an add-on.
On my old website I have my slides in the same repo as my course website. However, I somehow could not manage to do the same on the Quarto website. Quarto renders all documents and stores them in a folder called _site. I was able to get a file such as slides/week01/some-file.qmd to be rendered in the _site folder. However, anything inside slides/week01/img/ folder would not show up. So I gave up and created a separate repo for my slides. In my other course, I also have starter-codes folder with .qmd files that students download before each class. Despite having .qmd file links to be downloaded, since _site essentially is where all the files are these files are downloaded as .html. Thus I needed a separate repo for starter-codes. as well.
I have not run into this issue yet because I am the only one building websites yet but I am expecting to run into more merge conflicts if multiple people maintain websites since many files in _site have too many system-dependent components.
Quarto supports multiple-column views which I use quite frequently. It is ideal when I want to show things side by side. However, sometimes I just want to float things on the right and then have the rest of the text appear one by one. This would not be possible in a two-column view. It made me miss xaringan’s pull-right so much that I defined classes in my CSS.
I am a big fan of the fact that R Markdown and Quarto (i.e., knitr) support alternate text so much so that I requested the feature. One great thing about about the RStudio interface is even if one writes a very long alternate text it would wrap the text so we don’t have to scroll forever to read the text. However, this is not wrapped, for instance, in slides. One has to scroll to the right a lot!!! Slides being different from students’ own experiences in writing in Quarto doc is not the ideal learning experience.
Overall, I really love the Quarto experience for preparing my slides, handouts, etc. I can’t yet say the same for making websites but I think I’ll continue using Quarto rather than plain HTML for consistency and accessibility for community members.