search

yihui / litedown

A lightweight version of R Markdown
https://yihui.org/litedown/
Other
175 stars 3 forks source link

`html_vignette` v `html_format` #22

Closed TimTaylor closed 1 month ago

TimTaylor commented 2 months ago

For vignettes, do you still advise using html_vignette versus html_format? The main difference I've observed is that html_vignette does not seem to allow embedding of https resources.

FI - I've also found that pkgdown can handle html_format but not html_vignette. I'm aware this is more a consideration for pkgdown authors than yourself but just wanted to flag for awareness.

yihui commented 2 months ago

I recommend using html_format: https://yihui.org/litedown/#sec-package-vignettes But it shouldn't make a difference, since html_vignette is basically an alias of html_format.

html_vignette was introduced for the sole purpose of transitioning from rmarkdown to litedown. For these who want to stay with litedown in the long run, the only "official" formats are litedown::html_format and litedown::latex_format.

FI - I've also found that pkgdown can handle html_format but not html_vignette. I'm aware this is more a consideration for pkgdown authors than yourself but just wanted to flag for awareness.

That's probably because html_vigette is not exported from litedown, and I don't plan to export it. Please also note that litedown is not strictly compatible with rmarkdown (on which pkgdown is based). Some features won't work in pkgdown, and some may work differently. That said, it's possible that litedown will have its own implementation of package documentation someday.

TimTaylor commented 2 months ago

That's probably because html_vigette is not exported from litedown, and I don't plan to export it. Please also note that litedown is not strictly compatible with rmarkdown (on which pkgdown is based). Some features won't work in pkgdown, and some may work differently.

Cheers. Yeah I'm aware I'm very much kicking the tyres at the moment.

That said, it's possible that litedown will have its own implementation of package documentation someday.

Cool (choice is important for a healthy R ecosystem) but don't burn yourself out if you decide to take this on.

I'm sure you're already aware but, just in case you aren't, Deepayan Sarkar has been working on single page documentation (https://github.com/deepayan/r-refmans) for R-core. Perhaps there is some useful overlap.