add items for vignettes

[hturner]

A couple of packages considered but not added:

• RmdConcord - perhaps put in section on debugging issues from checks
• readme2vignette - for package users rather than developers (converts README to vignette when there are no vignettes)

[llrs]

Perhaps in the introduction about the vignettes it would be nice to talk about the engines and the functions: an overview of how it works might help understand why packages and specific functions are mentioned.

[llrs]

Here katex is mentioned (see also notes on #11 ), I just make a link to it.
I'm not familiar with katex or mathematical writing in Rd but I don't understand how to set the math_method argument in katex. Perhaps only mention that katex should be used for users to read about how to do this. Similarly new users might be confused with the engine and the functions from knitr and (r)markdown.

Suggested change

- `r pkg("knitr", priority = "core")` provides vignette engines to compile HTML and PDF vignettes via `knit()`. The `knit::rmarkdown` engine can be used with the `html_vignette()` output format from `r pkg("rmarkdown")`, which is a lightweight alternative to `knitr::html_document()`. For mathematics to render offline, the `math_method` argument should be set to `"katex"`. Using the `knit::knitr` engine with `html_format()` from `r pkg("markdown")` produces similar results with far fewer dependencies (as `r pkg("rmarkdown")` is no longer required).

- `r pkg("knitr", priority = "core")` provides vignette engines to compile HTML and PDF vignettes via `knit()`. The `knitr::rmarkdown` engine can be used with the `html_vignette()` output format from `r pkg("rmarkdown")`, which is a lightweight alternative to `knitr::html_document()`. For mathematics to render offline, the `math_method` argument should be set to `r pkg("katex")`. Using the `knitr::knitr` engine with `html_format()` from `r pkg("markdown")` produces similar results with far fewer dependencies (as `r pkg("rmarkdown")` is no longer required).

About the engine used, I would check what is the best approach. I think that CRAN or Yihui prefers one over the others (I don't remember well which one). There were some messages on r-package-devel some months/year(s?) ago.

[hturner]

I have tried to revise in light of your comments:

• Extend introduction paragraph a little, to be more specific about vignette engines. Add direct link to Non-Sweave vignettes section of WRE for further reading.
• Reword bullet point on vignettes with knitr:
  • Drop mention of knit() as that is an implementation detail
  • Prefix all output format functions to be clear which package they come from.
  • Clarify that "katex" is a recommended setting for the "math_method" argument of rmarkdown::html_vignette(), not a package name. However, "r-katex" is an equally valid setting that does use the {katex} package and I have added this option (without given the detail).
• Add reasons why each alternative for producing vignettes may be preferred.

Although it adds complexity, I think it's important to mention the katex issue as rmarkdown::html_vignette() is currently the default used by usethis::use_vignette(), hence or otherwise there are many vignettes where the math does not render offline as people do not realize that this is the behaviour of the default MathJax rendering.

{data.table} made a big move from rmarkdown::html_vignette() to markdown::html_format() to reduce dependencies - I couldn't find a related discussion on the mailing lists, but Yihui joined in the discussion on the data.table repo. This leads to my comment that "markdown::html_format() produces similar results for simple vignettes and may be preferred, as r pkg("markdown") has fewer dependencies than r pkg("rmarkdown")."

I think these days, @yihui would recommend {litedown}, as it is also lightweight and more fully-featured than markdown::html_format(). {litedown} is very new - only one package other than litedown is using it on CRAN - but data.table are now considering it. That is why I added {litedown} as a "core" package and say "can be recommended for new packages".

Quarto vignettes are also very new, though they have a little more take up, probably due to familiarity/Quarto being more well known. Using Quarto removes R package dependencies, but adds Quarto, so I wouldn't call it lightweight.

[yihui]

Just one quick note: {markdown} has been superseded by {litedown} (the former is a strict subset of the latter). The two packages have identical dependencies (i.e., {xfun} and {commonmark}), but {markdown} only focuses on the Pandoc part, and {litedown} = min{knitr + evaluate + rmarkdown + bookdown + blogdown + pagedown + pkgdown + xaringan + tufte + distill} - Pandoc. So yes, I'd recommend {litedown} but would also give it a bit more time to mature. Currently only {nanonext}, {mirai}, and {ympes} are using the litedown::vignette engine (I think {data.table} will also switch over at some point).