R Package Vignettes with Markdown | /en/2012/09/r-package-markdown-vignettes/

yihui 2022-12-16 23:02:42

R Package Vignettes with Markdown

https://yihui.org/en/2012/09/r-package-markdown-vignettes/

5 Comments

giscus-bot 2022-12-16 23:02:43

Guest *Guest* @ 2013-01-26 01:39:08 originally posted:

The only thing holding me back from using markdown for my vignettes is the the ability to have a table of contents. I'm sure I could write something to take care of this but I'm wondering if there is something in knitr that will already take care of this for me?

yihui 2022-12-16 23:02:47

No in knitr, but in the markdown package using the toc option. Instead of a plain call to knit2html(), you can add the toc option, e.g.

knit2html(..., options = c('toc', markdown::markdownHTMLOptions(TRUE))

See ?markdownToHTML in the markdown package for details. Also see the formatR package for a real example: https://github.com/yihui/formatR

Originally posted on 2013-01-26 05:03:22

giscus-bot 2022-12-16 23:02:44

Guest *Eliezer Gurarie* @ 2013-06-08 19:56:22 originally posted:

Thank you as always for your wonderful tools.

One question: once I have built a package with an html vignette, I have a hard time accessing it through R.

browseVignettes("mypackage") provides links, but to a directory: "library/mypackage/doc/myvignettes.html", whereas the actual directory is "win-library/3.0/mypackage/doc/...". This is actually a problem for any vignette I look up - making browseVignettes() useless - though the "vignette()" function works fine.

When I open the "00Index.html" file, there are links to the vignettes, but they look in "win-library/library/mypackage/doc/myvignette.html" which is also wrong.

I have no idea how to change the linking directories - (and am surprised, since the "build" surely knows where it is writing the package to!)

ANY help is appreciated! Also - if this is not the best place to post this question let me know.

Thanks,

Eli

yihui 2022-12-16 23:02:48

If you want the real directories, use system.file('doc', 'myvignette.html', package = 'knitr')

Originally posted on 2013-06-09 03:09:29

giscus-bot 2022-12-16 23:02:50

Guest *Eliezer Gurarie* @ 2013-06-09 04:17:14 originally posted:

Thanks - yes, you can always find and open the file. But it seems unsatisfactory that neither the "home page" of the package nor "browseVignettes" work. Is this (at least the first) a problem at the "build" level?

giscus-bot 2022-12-16 23:02:50

Guest *Eliezer Gurarie* @ 2013-06-11 17:21:22 originally posted:

UPDATE - PARTIAL SOLUTION: I had to create (and edit) an .Rprofile in my home directory with a single "lib.Paths( foo )" command (following suggestions here: http://stackoverflow.com/questions/16049259/rstudio-different-library-path-to-command-line-r-r-libs-user).

This fixed browseVignettes() perfectly, but mysteriously - caused the RStudio build OR knitr to no longer work (because it was reverting to trying to write to the wrong library). So I deleted .Rprofile instead and manually edited the "Rprofile.site" file in the R "etc" directory.

Basically, it sounds like somewhere there is a disconnect between the library path variables in R consoles, RStudio console, and knitr / building environements.

(I realize this is quite off topic for knitr + vignette - but thought I'd share this unintuitive experience).

giscus-bot 2022-12-16 23:02:45

Guest *Phil Chalmers* @ 2014-06-17 14:55:28 originally posted:

Hey Yihui,

I like the idea of generating HTML's via markdown rather than the cumbersome/eye bleeding LaTeX approach, but I have a question.

Is it possible to include locally compiled HTML files using this approach? My vignette files often take a little while to generate, and I want to avoid headaches generated from the R CMD check (and the goaltenders who care about this at submission time.....). Plus, I don't want them to be compiled every time I run a build since that generates more overhead for things like Travic CI.

This directly relates to your stack overflow response a while back for pdf files, but now for HTMLs (http://stackoverflow.com/questions/13128928/can-i-have-r-vignette-with-a-pre-compiled-pdf-with-manual-index-html-show-up-the). Cheers.

yihui 2022-12-16 23:02:51

I think you can put the HTML files under the vignettes/ directory, and readLines() them into your vignette, then cat(sep = 'n') with the chunk option results = 'asis'.

Originally posted on 2014-06-19 05:53:28

giscus-bot 2022-12-16 23:02:52

Guest *Phil Chalmers* @ 2014-06-19 14:21:40 originally posted:

Clever. Thanks Yihui!

giscus-bot 2022-12-16 23:02:46

Guest *Viliam Simko* @ 2016-03-18 11:58:26 originally posted:

Dear Yihui,
I'm a contributor to the corrplot package. We have recently released a new version and it doesn't contain the "inst" directory anymore.
The original "inst/doc/index.Rmd" file is now located in "vignettes/" folder.

See this link:
https://github.com/taiyun/corrplot/blob/master/vignettes/corrplot-intro.Rmd

Best regards,
Viliam

yihui 2022-12-16 23:02:53

Thanks. Fixed now.

Originally posted on 2016-04-14 06:24:13

giscus-bot 2022-12-16 23:02:47

Guest *Anne Kümmel* @ 2017-03-31 07:15:09 originally posted:

Dear Yihue!
I am wondering whether it is in a way possible to build an interactive vignette.
I tried with shiny, but as far as I understand this, I have to use rmarkdown::run and not rmarkdown::render to generate the html document.
But this cannot be incorporated into the vignette of a package.

Is there a solution to that

Regards
Anne

yihui 2022-12-16 23:02:54

No, it is not possible. R package vignettes are supposed to be static. If you have anything interactive, like a Shiny app, in the vignette, your only choice is to publish the app separately (e.g. to ShinyApps.io), then embed the app in the static R Markdown vignette via the HTML tag iframe.

Originally posted on 2017-03-31 18:28:33

giscus-bot 2022-12-16 23:02:55

Guest *Anne Kümmel* @ 2017-04-02 07:00:21 originally posted:

Hej Yihui!

I suspected that. Thanks for confirming and pointing out the trick of embedding an app.

Anne