pkgdown ignores vignettes that R recognises

[eddelbuettel]

In one package which uses pkgdown to create documentation, I recently switch to a different vignette engine which also uses markdown. And from that package, R recognises all vignettes (as seen via browseVignettes(package="nameOfPackage") just fine.

Yet pkgdown ignores all of them.

What appears to happen is that pkgdown lists files names vignettes/*.Rmd. But that is not what R does as these vignettes (for which I used the extension .md) are perfectly picked up by R itself. Once I "give in" and rename the vignettes to .Rmd it still (partially) fails as titles are not picked up (which base R recovers perfectly) from VignetteIndexEntry fields.

All this is perfectly defensible if it were documented (which I don't think it is). Is pkgdown working only with rmarkdown html vignettes? If not, could we extend to it maybe use a union of what it sees in vignettes/ and what R sees? I ended up getting perfectly valid output once I a) renamed my vignettes and b) added a YAML header. Neither one of those is a base R requirement.

[hadley]

pkgdown can't automatically work with any vignette supported by R because it has to be able to construct the vignette in such a way that it integrates with the rest of the site. We can make sure this is more clearly documented in the future.

[eddelbuettel]

For reference, it works perfectly fine with a another vignette engine once you

• rename files to *.Rmd (or else pkgdown ignores them and no 'Articles' section is created)
• add a YAML header with field Title (or else Title is unset though R finds it from required VignetteIndexEntry)

So not actually a documentation issue, rather a more-restrictive-than-R setup by either choice or accident.

In a more perfect world someone might extend the functionality as described. In the world we live in it may get labelled away as a "documentation issue".

[dmurdoch]

Something that might allow inclusion of arbitrary files (without attempting integration) would be to list them as external files, e.g. see https://pkgdown.r-lib.org/reference/build_articles.html#external-files . I don't know how that would interact with the two workarounds you mention.

[eddelbuettel]

The integration is actually nice and something you might want (hence my renaming / re-yamling dance) as the CSS is pretty and the pkgdown engine correctly picks up structural elements from what pandoc et al parse and uses it for the page(s). That's the part that is ... somewhat frustrating as the behaviour is overly restrictive when it has no reason to be.

[hadley]

It looks like this is documented (minimally, at least) in https://pkgdown.r-lib.org/reference/build_articles.html#output-formats.