How to have `pkgdown` use figure numbers and cross-references in vignettes?

[friendly]

This is a question I posted on SO, https://stackoverflow.com/questions/73911723/how-to-have-pkgdown-use-figure-numbers-and-cross-references-in-vignettes but without any response, so I'm hoping that someone here can suggest a solution. Or if not, perhaps this is something that the pkgdown team can consider as an enhancement.

I refer to the new pkgdown site for my heplots package, http://friendly.github.io/heplots/ , with the source at https://github.com/friendly/heplots

My description in the SO post:

I've created several vignettes for a package, with figures I want to reference in the text. Using the template for a .Rmd vignette, I can do this by using bookdown::html_document2 as follows in my yaml header:

output: 
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
    fig_caption: yes
    toc: true

Yet, when I build the associated pkgdown site, I don't get figure numbers or cross-references, done with \@ref(fig:chunk_name).

What I see in the pkgdown-rendered articles has (a) no figure numbers; (b) figure cross-references just appear in the rendered articles as @(fig:chunk-name)

[dmurdoch]

Does this pkgdown issue solution help: https://github.com/r-lib/pkgdown/issues/323#issuecomment-580223223 ?

On 02/10/2022 1:23 p.m., Michael Friendly wrote:

This is a question I posted on SO, https://stackoverflow.com/questions/73911723/how-to-have-pkgdown-use-figure-numbers-and-cross-references-in-vignettes https://stackoverflow.com/questions/73911723/how-to-have-pkgdown-use-figure-numbers-and-cross-references-in-vignettes but without any response, so I'm hoping that someone here can suggest a solution. Or if not, perhaps this is something that the |pkgdown| team can consider as an enhancement.

I refer to the new pkgdown site for my |heplots| package, http://friendly.github.io/heplots/ http://friendly.github.io/heplots/ , with the source at https://github.com/friendly/heplots https://github.com/friendly/heplots

My description in the SO post:

I've created several vignettes for a package, with figures I want to reference in the text. Using the template for a |.Rmd| vignette, I can do this by using |bookdown::html_document2| as follows in my yaml header:

|output: bookdown::html_document2: base_format: rmarkdown::html_vignette fig_caption: yes toc: true |

Yet, when I build the associated |pkgdown| site, I don't get figure numbers or cross-references, done with @.***(fig:chunk_name)|.

What I see in the pkgdown-rendered articles has (a) no figure numbers; (b) figure cross-references just appear in the rendered articles as |@(fig:chunk-name)|

— Reply to this email directly, view it on GitHub https://github.com/r-lib/pkgdown/issues/2201, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAOYSQCTR6SSTUTXKAJ4VJDWBHAI3ANCNFSM6AAAAAAQ27QNUU. You are receiving this because you are subscribed to this thread.Message ID: @.***>

[friendly]

Wow! Thx @dmurdoch

For the record, the suggestion is to add a pkgdown: asis: true to the yaml header of vignettes, one of mine looks like:

---
title: "HE plot MMRA Examples"
author: Michael Friendly
date: "`r Sys.Date()`"
package: heplots
output: 
  bookdown::html_document2:
    base_format: rmarkdown::html_vignette
    fig_caption: yes
    toc: true
    toc_depth: 2
pkgdown:
  as_is: true
bibliography: "HE-examples.bib"
link-citations: yes
...
---

I get all figures numbered and cross-references work.

However, I also get a large number of warnings, which may be specious (?) or mean that my chunk labels aren't recognized by pkgdown

There were 13 warnings (use warnings() to see them)
> warnings()
Warning messages:
1: The label(s) fig:rohwer-HE2 not found
2: The label(s) fig:rohwer-HE3D not found
3: The label(s) fig:rohwer-HE1 not found
4: The label(s) fig:rohwer-HE4 not found
5: The label(s) fig:rohwer-HE4 not found
6: The label(s) fig:rohwer-HE2 not found
7: The label(s) fig:rohwer-HE4 not found
8: The label(s) fig:hern-can1, fig:hern-can2 not found
9: The label(s) fig:grades-pairs not found
10: The label(s) fig:grades-HE3D not found
11: The label(s) fig:grades-can-class not found
12: The label(s) fig:grades-can-class not found
13: The label(s) fig:grades-can-all not found

Recommendation At the very least, I recommend that this problem be documented in pkgdown, with the solution to add pkgdown: asis: true to the yaml header of each vignette

[hadley]

It looks like the necessary docs are in https://pkgdown.r-lib.org/reference/build_articles.html#output-formats.

Additionally, I'll soon start work on quarto support (#2210) where hopefully all you'll need to do to get nice figure numbers + cross-references is switch from .Rmd to .qmd.