Learning by doing: migrating to Quarto from Bookdown

Learning by doing: migrating to Quarto from Bookdown

I just had rather a lot of fun working with Ileana Fenwick to convert a book to Quarto from RMarkdown! Given that Quarto is relatively new and there’s not yet an excess of resources beyond the official docs, we’ve documented how we did it.

First, what is Quarto? It is a new open-source scientific and technical publishing system, building on ten years of what RStudio learned from RMarkdown, and extends these features beyond R. While RMarkdown isn’t going away, we have been transitioning some RMarkdown projects to Quarto so that there is a consistent way to contribute, whether folks are familiar with R, Python, or new to this kind of open-science workflow all together.

And what was the fun about? Lots of things. The book we converted is Gavin Fay’s outstanding onboarding documentation, the Faylab Lab Manual. The technical work was at the right level of new-ness and challenge for us and we approached it by coworking and screensharing over a few sessions before moving to asynchronous work. Plus, most often when we tried something it “just worked” because Quarto can handle RMarkdown and this book was mostly prose and screenshots without any R (or Python) code.

There is joy in our commits!

We started by familiarizing ourselves through Mine Çetinkaya-Rundel’s “Reproducible authoring with Quarto” (slides, YouTube), Danielle Navarro’s “Porting a distill blog to quarto”, and Nick Tierney’s Notes on Changing from Rmarkdown/Bookdown to Quarto. In June, we participated in the Community Call, A Quarto Chat with NASA Openscapes, co-hosted with R-Ladies Santa Barbara. It was relatively straightforward to figure basic things out by searching the Quarto documentation, coming back to those resources, and checking out the GitHub sources of other Quarto books to see how others have set things up.

Here’s the GitHub view of the Faylab Lab Manual before and after migration. As is the Openscapes practice, we documented what we did - for Future Us and for you - in the Bookdown to Quarto section of our open-source tutorial, Making shareable documents with Quarto.

As is also the Openscapes practice, I’m learning (… trying to learn) to embrace “done for now, not perfect”. “Making shareable documents with Quarto” is a living document in which we aim to describe things as clearly as possible in the time we have, share it with others, and improve as we come back to it. If we wait till we have time to write flawless docs, it’ll never happen. This is such a safe place to grow one’s comfort zone!

This migration took us about 19 combined hours, which includes time reading, learning, trying things, and fixing things. This also includes learning that when you fork a repo and then make a branch, by default the branch’s pull request goes to the original repo not your fork (d’oh!). Our GitHub Action to render the Faylab Lab Manual failed initially because we had a piece of R code - even though the code was commented out! That was resolved when we deleted the line. On the plus side, we saw the ease of adding citations via DOI in the RStudio Visual Editor (tutorial; YouTube). The time spent learning is already paying off as I (Stef) contribute to our other open documentation in Quarto, like our Guide to the Openscapes Approach (GitHub).

If you’d like to become more familiar with Quarto, we hope this post helps. You can also try our Quarto website tutorial, which we’ve been developing as we’ve learned and taught others. See something that needs improving? Open a GitHub issue to tell us about it (the tutorial will point you to resources for creating an account if this is your first time). Or remix it by forking, adapting, and citing the repo.

Thanks to Gavin Fay, an Openscapes Champion, for allowing us to experiment and learn by migrating his inspiring lab manual, and to Julie Lowndes, Openscapes Director, for guiding us along the way!