Can R package vignettes be written in Quarto?

[dcnorris]

I see that even the quarto package has an Rmd vignette, so I assume the answer is "not yet".

Are there plans to support Quarto vignettes? Might a quarto VignetteEngine be provided to replace knitr::rmarkdown? Or are are there deeper issues, e.g. aspects of Quarto's design that are incompatible with R package vignettes?

[mcanouil]

I don't think it's going to happen in a near future because CRAN would need to add Quarto binary to their setup.
So, this is entirely up to the R Core Team.

[dcnorris]

It's better to let CRAN catch up with advances than to give it veto power over them. CRAN has operational constraints and design aims that (perhaps quite appropriately?) are incompatible with rapid progress. Adding compiled Rust code to my R package precautionary, necessitated that I abandon CRAN — for the time being, at least.

The best way to promote Quarto vignettes would be to 'build it and let them come'. After just a few days with Quarto, I already feel about Rmd the same way I felt about Sweave when I made that switch. I have little appetite to write another Rmd vignette!

[mcanouil]

We should give it a bit of time.
Quarto is only ~ 1.5 month old (birth: 28th of July 2022) 😅

Quarto makes more sense to me as Rmarkdown never has (I am not even talking about Sweave 😆).

[dcnorris]

Actually, this isn't nearly as hard as I imagined. Thanks to the example provided by @bdcaf's https://github.com/bdcaf/vignetteEngineMake, I see it's fairly straightforward to add Quarto vignettes to my package:

1. In the DESCRIPTION file, add your own package to the VignetteEngines line (let's say mine is called TOPSECRET):

VignetteBuilder: knitr, rmarkdown, TOPSECRET

2. Add an .onLoad function to your package (e.g., in a zzz.R file), to register a quarto vignetteEngine:

.onLoad <- function(libname, pkgname) {
  tools::vignetteEngine(name = "quarto",
                        package = pkgname,
                        pattern = "[.]qmd$",
                        weave = function(file, ..., encoding = "UTF-8") {
                          message("Hello from custom Quarto vignette engine!")
                          ## TODO: What is Quarto's expectation about encoding?
                          ## NB: output_format = "all" below might make a better default
                          quarto::quarto_render(file, ..., output_format = "pdf")
                        },
                        tangle = tools::vignetteEngine("knitr::rmarkdown")$tangle,
                        aspell = tools::vignetteEngine("knitr::rmarkdown")$aspell
                        )
}

3. In the YAML header for the Quarto vignette, specify the qualified vignetteEngine:

vignette: >
  %\VignetteIndexEntry{Whatever}
  %\VignetteEngine{TOPSECRET::quarto}
  %\VignetteEncoding{UTF-8}

This makes a perfectly workable solution for me. But I believe a cleaner way to do this would be to define several vignetteEngines in the quarto package — say quarto::pdf, quarto::html and even quarto::all. Then instead of the awkward self-reference in the VignetteBuilder line, you would simply write quarto.

[RaymondBalise]

Can someone please tell me the status on using Quarto for vignettes and CRAN? I am teaching package development next semester, and I would love to focus on Quarto instead of R Markdown. Is @denorris's .onLoad function (wizardry) still the way to go? Has a package with Quarto based vignettes made it onto CRAN?

[dcnorris]

Latest progress described here: quarto-dev/quarto-r#57 (review)

[cderv]

A quarto vignette engine is almost ready. It will be merged soon in quarto R package.

[RaymondBalise]

Hello @cderv. Can you share your guestimate on when Quarto based vignettes will be ready to roll? I am teaching package development this semester and I can, in theory, provide a solid test audience using Posit.Cloud if the timing is right.

[cderv]

This should be this week in v1.4 of Quarto R package that I am finalizing at : https://github.com/quarto-dev/quarto-r/

Tracked here.

• Using Quarto for creating vignettes quarto-r#136

[cderv]

For anyone who's interested and has not tested yet, the dev version of quarto R package now has some vignette engines registered.

Please open new issues in https://github.com/quarto-dev/quarto-r for ideas, or any other feedback thanks!

[RaymondBalise]

Is there an example showing the YAML header to make an R package vignette with Quarto? usethis::use_vignette() gives this header:

---
title: "demo"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Is there a similar usethis function planned for quarto based vignettes?

[cderv]

For now usethis does not have a function for this. The example is given by Quarto own vignette and looking at demo vignette in the package (vignette("hello", package = "quarto")).

This would be

---
title: "demo"
vignette: >
  %\VignetteIndexEntry{demo}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

pkgdown does not handle Quarto vignette either, so they can't show on the website if they use Quarto feature - I'll create a new article not using quarto specifically for this I guess.