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: #323 (comment) ?

…

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 <#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.