search

r-lib / usethis

Set up commonly used 📦 components
https://usethis.r-lib.org/
Other
866 stars 286 forks source link

Feature request: Add `use_readme_qmd()` #1671

Open maia-sh opened 2 years ago

maia-sh commented 2 years ago

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 commented 1 year ago

Along the same lines, will use_quarto_template become a thing?

JosiahParry commented 1 year ago

Adding a vote for use_readme_qmd()

jennybc commented 1 year ago

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

JosiahParry commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 10 months ago

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 commented 4 months ago

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 commented 3 months ago

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 commented 6 days ago

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 commented 5 days ago

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

https://github.com/quarto-dev/quarto-cli/issues/6092#issuecomment-1618063261