Feature request: Add use_readme_qmd()

[maia-sh]

I'm slowly shifting from RMarkdown to Quarto, and it would be great to have a use_readme_qmd() in addition to the Rmd and Md README functions.

[daranzolin]

Along the same lines, will use_quarto_template become a thing?

[JosiahParry]

Adding a vote for use_readme_qmd()

[jennybc]

Is there some specific reason you want README.qmd? Like "it lets me do X which I can't do with .Rmd".

[JosiahParry]

From my perspective, no. It's more in an attempt to adopt quarto entirely. If quarto is to truly be a modernization and replacement for R Markdown, then I want to use it ubiquitously

[JosiahParry]

@jennybc I'm writing a package article I created with usethis::use_article() and am coming across use cases where I would like to use quarto features.

In one case I want to have a few different call out types as provided at https://quarto.org/docs/authoring/callouts.html#callout-types

In another I am providing instructions to users to populate the contents of their .Renviron file and would like to use the code filename pattern here: https://quarto.org/docs/output-formats/html-code.html#code-filename

Another situation is the use of :::{.aside} for useful asides.

[jennybc]

I don't see us creating special infrastructure for quarto articles (vs. vignettes). I suspect quarto features won't be fair game in articles until / unless quarto becomes officially supported for vignettes, which is a base R and CRAN matter.

README is a bit different, since "we" control the conversion of README.Rmd (or, in theory, READMD.qmd) to README.md.

I think if you really want to use quarto features in an article, you might investigate the "pre-compiled article/vignette" approach.

See the callout in this section for tips: https://r-pkgs.org/vignettes.html#sec-vignettes-how-built

You could conceivably bring this up in pkgdown, though, I guess.

[JosiahParry]

I think that all makes sense! I'll let sleeping dogs lie.

As an aside... though I couldn't find it online, would it be conceivable that the CRAN machines have quarto available? I know that they have Rust available, for example, but it's not documented.

However, it’s important to note that the package bundle and binaries distributed by CRAN actually use the built vignettes included in your submission. Yes, CRAN will attempt to rebuild your vignettes regularly, but this is for quality control purposes. CRAN distributes the vignettes you built.

Wow. Nuts. So if they didn't try and rebuild the vignette it might not even be a problem. But, alas!

[dmurdoch]

@jennybc : In theory a package could provide a vignette engine that associated .qmd files with R code to convert them to .html or .pdf, and then they could be vignettes. I think the package might need to include a quarto interpreter if you wanted this to be acceptable on CRAN. I don't know if that's feasible or not.

[jennybc]

Thanks @dmurdoch. I assume this sort of conversation is coming, as quarto gains traction. But I think usethis will be more of a passenger than a driver.

[kleinlennart]

For me the biggest reason to switch from .Rmd to .qmd for READMEs is the native support for mermaid when exporting to gfm. Would be great if you could include it as a dedicated function, but otherwise manually changing the pre-commit git hook and YAML header is also not a big problem.

https://quarto.org/docs/authoring/diagrams.html#mermaid-formats

[dmi3kno]

I switched completely to Quarto readme files with

format: gfm

I was struggling with pre-commit hooks which have been installed by usethis to control that .md is never committed without .Rmd. (see #312 ) and had to manually remove the pre-commit hook file like recommended here. Would prefer to have it allow either Rmd or Qmd committed along with md.

[wzbillings]

Would prefer to have it allow either Rmd or Qmd committed along with md.

You can open the file .git/hooks/pre-commit in the RStudio editor and change the "R"s to "q"s, then it will work with qmd files.

[jennybc]

usethis has recently gained support for placing Quarto (.qmd) vignettes and articles. I'm talking about the version that I hope will be released as usethis 3.1.0, if my current CRAN submission ends well.

So I think this issue's time has now come.

[yutannihilation]

I really want use_readme_qmd(). I always hit this pitfall about badges and can never remember the option!

quarto-dev/quarto-cli#6092 (comment)