Pkgdown: Implement bookdown like cross references

[wjakethompson]

I currently use bookdown for writing vignettes by adding the following to the YAML metadata:

output:
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
    number_sections: false

This allows me to reference equations and figures using the \@ref(eq:some-equation) syntax, and the vignettes render as you would expect. However, when using pkgdown::build_articles(), the cross references are no longer supported, and thus don't display correctly. It would be nice if pkgdown were also able to use the cross references feature.

[hadley]

@yihui any ideas what I need to do to make this work?

[yihui]

Looks like the output format is hard-coded as rmarkdown::html_document: https://github.com/hadley/pkgdown/blob/721c8430/R/build-articles.R#L136

Replacing it with bookdown::html_document2 might work.

[hadley]

I'm not sure how easy that will be to do and still retain all the custom pkgdown stuff. What does html_document2 to make the cross-links work?

[yihui]

bookdown::html_document2 is built on top of rmarkdown::html_document. Basically it added a post-processor to resolve the cross-references. It should be safe to use, but I'm not totally sure what pkgdown does to the HTML output. A conservative strategy is to detect the output format specified by the user, e.g. use html_document2 only if it is detected, otherwise use the default html_document.

[hadley]

@yihui do you think adding bookdown:::resolve_refs_html to config$post_processor would be sufficient to get this one thing working?

[yihui]

Yes. Just make sure its global argument takes the value !number_sections from html_document.

[nsheff]

Just to further extend this: it would be nice if pkgdown were compatible with other vignette styles more generally. For example, my vignettes specify BiocStyle but pkgdown renders them using the rmarkdown style.

Being able to use the output specified by the vignette instead of hard-coding either rmarkdown::html_document or even bookdown::html_document2 would be a nice feature.

[hturner]

A couple of specific issues converting BiocStyle vignettes:

• you lose the Figure 1:, Table 1: prefixes to captions (maybe this is related to cross-ref issue?)
• the abstract title isn't formatted as a title

I wouldn't especially mind losing the BiocStyle style, if these issues could be fixed/worked around. In my case switching to bookdown::html_document2 could be a viable solution, but it would be good if the standard Bioconductor style were supported.

[hturner]

I've now created a function to post-process the HTML created by pkgdown::build_articles that will fix these issues (plus a couple of other style issues). I've just posted it as a gist as this is a hack that will hopefully be superseded by a better solution in pkgdown itself: https://gist.github.com/hturner/5202ee24e7f2db02ed9ab4b2e1805dac. An example output can be seen here: https://hturner.github.io/PlackettLuce/articles/Overview.html - not as tidy as actual Biocstyle output, e.g. there is no special treatment of wide figures, but at least the major issues are fixed.

I've not tested it with bookdown::html_document2 but I imagine it would work as the same issues arise with captions and referencing tables and figures.

[aoles]

Many thanks @hturner for taking the time to look into the compatibility issue of BiocStyle with pkgdown and for sharing your solution to it.

An alternative more general approach to resolving cross-references with pkgdown could be redefining the internal function in pkgdown to use bookdown::html_document2 instead of rmarkdown::html_document by calling the following before running pkgdown::build_articles() or pkgdown::build_site(). Any custom CSS rules should be put under pkgdown/extra.css as advised in https://github.com/hadley/pkgdown/issues/317.

assignInNamespace(
  "build_rmarkdown_format",
  ns = "pkgdown",
  value = function(pkg = ".",
                   depth = 1L,
                   data = list(),
                   toc = TRUE) {
    # Render vignette template to temporary file
    path <- tempfile(fileext = ".html")
    suppressMessages(pkgdown::render_page(pkg, "vignette", data, path, depth = depth))

    list(
      path = path,
      format = bookdown::html_document2(
        toc = toc,
        toc_depth = 2,
        self_contained = FALSE,
        theme = NULL,
        template = path
      )
    )
  }
)

[hturner]

Thanks @aoles, this is a neater solution! For better compatibility with Biocstyle, I added number_sections = FALSE to the html_document2 call - obviously if someone is using bookdown::html_document2 to start with they may not want this. Perhaps this gives an idea of what would be useful for users to change - either as part of the call to build_site/build_articles, or derived from the YAML of the vignette source.

I needed to change my css a bit, but otherwise this works nicely! I have created a new gist with your modified build_rmarkdown_format and my extra.css in case others want to use/modify it: https://gist.github.com/hturner/3152081e223ade0bb212bcef19f183bf

[hadley]

I don't think I can make pkgdown respect the output format recorded in the vignettes (since pkgdown has certain expectations about the generated html), but I think I should be able to make this configurable at the package level so you can do something like:

articles:
  output:
    html_document2:
      number_sections: true

[hadley]

Decided to go back to the earlier as_is idea.

[dfalster]

Thanks for building this great package, and for this update @hadley.

Having an as_is option seems like a great solution for custom outputs, but while this seems to work with your example in vignettes/test/output.Rmd, it doesn't seem to work properly with the bookdown::html_document2 format that motivated this issue. Specifically, the equations and equation numbering don't display when compiling a vignette via pkgdown, whereas they do when compiling the same doc with knitr.

As background, I have been using the hackers method described in @hturner's gist to get equation numbers displaying in my pkgdown site (e.g. https://traitecoevo.github.io/plant/articles/demography.html). I'm now trying to get this working using your suggested approach but can't the equations to show.

Below is an example for a complete Rmd file setup to use the bookdown::html_document2 output format. Save into the folder vignettes in a test package.

title: "Test: Custom output (bookdown equations)"
output: 
  bookdown::html_document2:
    toc: yes
    toc_depth: 2
    number_sections: FALSE
pkgdown:
  as_is: true
---

By using the bookdown::html_document2 format we should be able to render equations with labels. 

Below should show an equation, with label here -> \@ref(eq:size), even though this isn't possible with the default pkgdown default.

\begin{equation}
H(x, a_0, a) = H_0(x) + \int_{a_0}^{a} g(x, H(x, a_0, a^\prime), E_{a^\prime}) \, {\rm d}a^\prime
(\#eq:size)
\end{equation}

Compiling via knitr shows the equations:

whereas these are missing when compiling in pkgdown:

Can anyone verify if the equation numbers are displaying for them when compiling via pkgdown?

[pat-s]

The following header works for me to get figures cross-referenced:

---
title: "Get Started"
output: bookdown::html_document2
link-citations: yes
pkgdown:
  as_is: true
vignette: >
  %\VignetteIndexEntry{foo}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---