Pkgdown: Support rendering of pdf articles (e.g. using rticles templates)

[cboettig]

The default of behavior of ignoring the output format makes tons of sense for md or html-style vignettes, since of course we'd prefer the elegance of consistent CSS throughout the pkgdown site.

It makes less sense (and indeed may well not render properly) if a user has a nice PDF-style article, e.g. perhaps one rendered using a lovely rticles template for a particular journal. In this case, it seems preferable to render the pdf following the expected output format. I'm all for HTML-vignettes, but for journal articles (obviously thinking research compendia discussion) pdf is probably sensible.

[hadley]

There are two challenges:

• The UI needs to change: it's annoying if a link downloads a PDF without any warning.
• We need someway to specify vignettes that shouldn't have their output format overridden

[cboettig]

Very true.

I suppose introducing a field in the vignette yaml header might be the most natural way to set something like pkgdown_format:. For the UI, perhaps it would be sufficient to simply indicate the format after the article name, e.g. My Vignette (pdf)?

It may be less common than pdf, but I think the other format where this makes sense would be in html5 slides styles, since they tend to translate poorly when rendered directly in pkgdown html. If the user controls this behavior in yaml then the challenge remains on how to annotate the link; I suppose the parenthetical could be based on the output: *_document label?

[hadley]

Maybe it could just be pkgdown_asis: true?

Would you be interested in doing a PR for this? It's unlikely to get on to my to do list since I only ever use HTML vignettes.

[cboettig]

Happy to try, probably next time I'm doing a pkgdown site for a package that has some journal article in it. Will have to better acquaint myself with the pkgdown internals first.

[hadley]

Let me know before you work on it and I can give a quick overview. You'll probably need to modify render_rmd() and build_rmarkdown_format(). I don't think it should be too much work once we've finalised the convention for flagging the vignette.

[cboettig]

sounds good, thanks!

Yup, the convention for the yaml metadata is key. I like asis (matching the knitr term), though this field could also be applicable to blogdown as well, where occasionally it would be nice to render .Rmd output as pdf and/or html5_slides formats (https://github.com/rstudio/blogdown/issues/97, cc @yihui)

[jaredhuling]

Has there been any progress towards this end? I have a vignette that has fairly complicated tex dependencies and hence an html vignette won't work (as far as I can tell)

[pat-s]

I would also be interested in this!

[jaredhuling]

see here https://github.com/r-lib/pkgdown/pull/402 i haven't had time to fix it up

[hadley]

Actually, this is more challenging than I thought because you'll also need some way to figure out which vignettes will generate html, and which will generate pdf (or something else). tools:::find_vignette_product() seems to work (if I'm reading the code correctly) by looking at the output file, which is going to be challenging for pkgdown.

[hadley]

Oh, easy hack - just manually supply extension in pkgdown metadata in front matter.