Figure numbering is broken in HTML output with pandoc 3.x when using Markdown image syntax

[N0rbert]

Below is the minimal reproducible example (index.Rmd file):

---
title: Figure cross-reference issue in HTML
documentclass: book
site: bookdown::bookdown_site
output:
    bookdown::html_document2: default
---

```{r eval=TRUE, include=TRUE}
sessionInfo('bookdown')
rmarkdown::pandoc_version()
xfun::session_info('bookdown')
```

# Zero 1 {-#zero1}

Some text in 1st unnumbered section.

# Practically long header about some theories {#theory}

## Markdown Syntax {#markdown-syntax}

...

### Images {#markdown-syntax-media}

First figure of first section is below, it reference is Fig. \@ref(fig:md-logo).

![(\#fig:md-logo) Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)

...

While knitting this document using RStudio 2024.04.0 Build 735 with integrated latest pandoc 3.1.11 to HTML I get the wrong rendering

Here my figure is not numbered. So the cross-reference works as expected, but "Figure 1.1: " is not shown.

It is fresh installation of Ubuntu MATE 24.04 LTS.
Other details:

> xfun::session_info('bookdown')
## R version 4.3.3 (2024-02-29)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 24.04 LTS
## 
## Locale:
##   LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##   LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##   LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##   LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##   LC_ADDRESS=C               LC_TELEPHONE=C            
##   LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## Package version:
##   base64enc_0.1.3   bookdown_0.39.1   bslib_0.7.0       cachem_1.0.8     
##   cli_3.6.2         digest_0.6.35     evaluate_0.23     fastmap_1.1.1    
##   fontawesome_0.5.2 fs_1.6.4          glue_1.7.0        graphics_4.3.3   
##   grDevices_4.3.3   highr_0.10        htmltools_0.5.8.1 jquerylib_0.1.4  
##   jsonlite_1.8.8    knitr_1.46        lifecycle_1.0.4   memoise_2.0.1    
##   methods_4.3.3     mime_0.12         R6_2.5.1          rappdirs_0.3.3   
##   rlang_1.1.3       rmarkdown_2.26    sass_0.4.9        stats_4.3.3      
##   tinytex_0.50      tools_4.3.3       utils_4.3.3       xfun_0.43        
##   yaml_2.3.8

> rmarkdown::pandoc_version()
## [1] '3.1.11'

Running remotes::install_github("rstudio/bookdown") does not help.
Also please note that RStudio 2023.03.2-454 with pandoc 2.19.2 produces correct rendering.

[cderv]

Using a code cell to include the image works

```{r md-logo, fig.cap = "Markdown logo", echo = FALSE}
knitr::include_graphics("https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png")
```

The html produced at the end is

<div class="figure"><span style="display:block;" id="fig:md-logo"></span>
<img role="img" aria-label="Markdown logo" src="data:image/png;base64<...encoded...>" alt="Markdown logo" />
<p class="caption">
Figure 1.1: Markdown logo
</p>
</div>

When using the Markdown syntax as in example, Pandoc will produce this HTML

<div class="float">
<img role="img" aria-label=" Markdown logo" src="data:image/png;base64<...encoded...>" alt=" Markdown logo" />
<div class="figcaption"> Markdown logo</div>
</div>

bookdown is counting based on figure class

bookdown/R/html.R

Line 694 in 5dcce03

figs = grep('^<div class="figure', content)

and it does try to match caption not figcaption

bookdown/R/html.R

Lines 718 to 724 in 5dcce03

	if (length(grep('^<p class="caption', content[i - 0:1])) == 0) {
	# remove these labels, because there must be a caption on this or
	# previous line (possible negative case: the label appears in the alt
	# text of <img>)
	labs[[i]] = character(length(lab))
	next
	}

This is due to change in how images are rendered in Pandoc I believe

• jgm/pandoc@909ced5

This new API for figure was introduced in Pandoc 3

Pandoc 2.19.2

For the image syntax, we still get a Para with an Image

> pandoc::pandoc_convert(text = "![(\\#fig:md-logo) Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)", to = "native", version = "2.19.2")
[ Para
    [ Image
        ( "" , [] , [] )
        [ Str "(#fig:md-logo)"
        , Space
        , Str "Markdown"
        , Space
        , Str "logo"
        ]
        ( "https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png"
        , "fig:"
        )
    ]
]

Converted to html using figure

> pandoc::pandoc_convert(text = "![(\\#fig:md-logo) Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)", to = "html4", version = "2.19.2")
<div class="figure">
<img
src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png"
alt="" />
<p class="caption">(#fig:md-logo) Markdown logo</p>
</div>

Pandoc 3.0

This now is a Figure node

> pandoc::pandoc_convert(text = "![(\\#fig:md-logo) Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)", to = "native", version = "3.0")
[ Figure
    ( "" , [] , [] )
    (Caption
       Nothing
       [ Plain
           [ Str "(#fig:md-logo)"
           , Space
           , Str "Markdown"
           , Space
           , Str "logo"
           ]
       ])
    [ Plain
        [ Image
            ( "" , [] , [] )
            [ Str "(#fig:md-logo)"
            , Space
            , Str "Markdown"
            , Space
            , Str "logo"
            ]
            ( "https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png"
            , ""
            )
        ]
    ]
]

which leads to a different HTML

> pandoc::pandoc_convert(text = "![(\\#fig:md-logo) Markdown logo](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png)", to = "html4", version = "3.0")
<div class="float">
<img
src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/208px-Markdown-mark.svg.png"
alt="(#fig:md-logo) Markdown logo" />
<div class="figcaption">(#fig:md-logo) Markdown logo</div>
</div>

@yihui we need to adapt bookdown for this specific change when Markdown figure are used with labels

@N0rbert using knitr::include_graphics() writes html directly, so it will work as it still writes the correct HTML

[yihui]

I feel it's not a matter of simply changing two regular expressions, but will require us to write a Lua filter to transform the figure, which may not be trivial. Since a workaround exists, I tend to suggest using the workaround (i.e., knitr::include_graphics()).

[cderv]

I feel it's not a matter of simply changing two regular expressions,

Thanks for your look into it.

write a Lua filter to transform the figure,

I'll see what I can come up with. Maybe there is way to not produce this float from Pandoc 🤔

Since a workaround exists, I tend to suggest using the workaround (i.e., knitr::include_graphics()).

This is surely the best workaround in this case !

[N0rbert]

I have just tested this bug in the Debian 13 trixie (testing) with fresh R and bookdown.

> xfun::session_info('bookdown')
R version 4.4.3 (2025-02-28)
Platform: x86_64-pc-linux-gnu
Running under: Debian GNU/Linux trixie/sid, RStudio 2024.12.1.563

Locale:
  LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C         LC_TIME=C            LC_COLLATE=C        
  LC_MONETARY=C        LC_MESSAGES=C        LC_PAPER=C           LC_NAME=C           
  LC_ADDRESS=C         LC_TELEPHONE=C       LC_MEASUREMENT=C     LC_IDENTIFICATION=C 

Package version:
  R6_2.6.1          base64enc_0.1.3   bookdown_0.43     bslib_0.9.0      
  cachem_1.1.0      cli_3.6.4         digest_0.6.37     evaluate_1.0.3   
  fastmap_1.2.0     fontawesome_0.5.3 fs_1.6.6          glue_1.8.0       
  grDevices_4.4.3   graphics_4.4.3    highr_0.11        htmltools_0.5.8.1
  jquerylib_0.1.4   jsonlite_2.0.0    knitr_1.50        lifecycle_1.0.4  
  memoise_2.0.1     methods_4.4.3     mime_0.13         rappdirs_0.3.3   
  rlang_1.1.6       rmarkdown_2.29    sass_0.4.10       stats_4.4.3      
  tinytex_0.57      tools_4.4.3       utils_4.4.3       xfun_0.52        
  yaml_2.3.10      
> rmarkdown::pandoc_version()
[1] ‘3.2’
> 

The bug is still here.

I do not plan to change the contents of my 100+ Rmd files.

I'll continue to use previous stable versions - RStudio 2022.02.3+492 with bundled pandoc 2.17.1.1 and pandoc 2.17.1.1-2~deb12u1 for headless builds.
But please note that release of Debian 13 is approaching, so this bug may be disappointing.

[cderv]

Sorry for the delay @N0rbert - and thanks for the reminder.

Can you try #1496 ?

It solves the specific numbering problem. Hopefully, Pandoc 3 change from Img to Figure logic does not have other impact.