Add explicit figure caption for `github_document` using HTML

[tamas-ferenci]

Figure caption does not seem to work with github_document. Consider the following minimal reproducible example:

    ---
    title: "Test figure caption"
    output: github_document
    ---

    ```{r setup, include=FALSE}
    knitr::opts_chunk$set(echo = TRUE)
    library(knitr)
    ```

    ## Figure

    ```{r, fig.cap = "A caption"}
    plot(pressure)
    ```

Session info:

R version 4.2.0 (2022-04-22 ucrt)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 19044), RStudio 2022.2.3.492

Locale:
  LC_COLLATE=Hungarian_Hungary.utf8  LC_CTYPE=Hungarian_Hungary.utf8    LC_MONETARY=Hungarian_Hungary.utf8 LC_NUMERIC=C                      
  LC_TIME=Hungarian_Hungary.utf8    

Package version:
  base64enc_0.1.3 bslib_0.3.1     digest_0.6.29   evaluate_0.15   fastmap_1.1.0   fs_1.5.2        glue_1.6.2      graphics_4.2.0  grDevices_4.2.0
  highr_0.9       htmltools_0.5.2 jquerylib_0.1.4 jsonlite_1.8.0  knitr_1.39      magrittr_2.0.3  methods_4.2.0   R6_2.5.1        rappdirs_0.3.3 
  rlang_1.0.2     rmarkdown_2.14  sass_0.4.1      stats_4.2.0     stringi_1.7.6   stringr_1.4.0   tinytex_0.40    tools_4.2.0     utils_4.2.0    
  xfun_0.31       yaml_2.3.5     

Pandoc version: 2.17.1.1

The result is:

Checklist

When filing a bug report, please check the boxes below to confirm that you have provided us with the information we need. Have you:

• [x] formatted your issue so it is easier for us to read?

• [x] included a minimal, self-contained, and reproducible example?

• [x] pasted the output from xfun::session_info('rmarkdown') in your issue?

• [x] upgraded all your packages to their latest versions (including your versions of R, the RStudio IDE, and relevant R packages)?

• [x] installed and tested your bug with the development version of the rmarkdown package using remotes::install_github("rstudio/rmarkdown")?

[cderv]

What are your expectation with figure caption and github_document() ?

Here is the markdown produced by redering with github_document()

Test figure caption
================

## Figure

``` r
plot(pressure)
```

![A caption](test_files/figure-gfm/unnamed-chunk-1-1.png)

The value of fig.cap is correctly put in the caption part of the markdown syntax for figures.

However, I don't think Github Flavored Markdown supports rendering caption sets using markdown.

Are you looking for something like

---

This is screenshot of the reported issue

---

This is created using HTML directly

<figure>
<img src="https://user-images.githubusercontent.com/25476790/174912830-18a584ee-7956-4995-b57e-57cd42326114.png"
alt="A caption" />
<figcaption aria-hidden="true">This is screenshot of the reported issue</figcaption>
</figure>

Currently github_document produces markdown only (Github Flavored Markdown) and not HTML for specific content. We could think about it though to support that though. This would be a feature request in knitr probably

[tamas-ferenci]

Thanks you very much! Honestly, I didn't have any particular expectation, I was automatically assuming that the output in this respect should be the same as with output: html_document (i.e., the caption appearing).

[cderv]

the output in this respect should be the same as with output: html_document

We are trying to offer a preview of what the Markdown would looks like if you used it as a README.md on Github for example. And currently, github does not render ![A caption](image/path) with an explicit caption (like a figure environment).

I'll rename and leave that open as a feature request in case other users are interested to have real caption inserted in Github document as it seems we can do it because Github renderer will render the HTML https://github.github.com/gfm/#html-block

[tamas-ferenci]

And currently, github does not render

And it is possible that they don't want to change it as they consider [...] indeed just an alt text.

So yes, likely the only solution is to manually insert a caption below the figure in case of github_document.

Thank you!

[mikeroswell]

Just adding a comment that like @tamas-ferenci, I expected captions to render using the syntax above and would be interested in a feature that allows this!

[dushoff]

Real captions would be good, but I wonder if alt-text is more important. The inconsistency seems a shame, though.

[cderv]

Real captions would be good, but I wonder if alt-text is more important. The inconsistency seems a shame, though.

@dushoff can you explain the inconsistency your mention again ? Are you talking about GFM considering content in bracket within ![...]() as the alt text ?

@tamas-ferenci @mikeroswell @dushoff What would be for you the correct syntax for Github document ?

Currently this is what happens :

Using fig.alt

---
title: "Test figure caption"
output: github_document
---

## Figure

```{r, fig.alt="alt text"}
plot(pressure)
```

This will produce this GFM document

Test figure caption
================

## Figure

``` r
plot(pressure)
```

<img src="test_files/figure-gfm/unnamed-chunk-1-1.png" alt="alt text"  />

We create HTML code directly.

Using fig.cap

---
title: "Test figure caption"
output: github_document
---

## Figure

```{r, fig.cap="A caption"}
plot(pressure)
```

gives us

Test figure caption
================

## Figure

``` r
plot(pressure)
```

![A caption](test_files/figure-gfm/unnamed-chunk-1-1.png)

This produces markdown, but indeed the caption is considered as an Alt Text by GIthub (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images)

Using both

---
title: "Test figure caption"
output: github_document
---

## Figure

```{r, fig.cap="A caption", fig.alt = "alt text"}
plot(pressure)
```

gives us

Test figure caption
================

## Figure

``` r
plot(pressure)
```

<div class="figure">

<img src="test_files/figure-gfm/unnamed-chunk-1-1.png" alt="alt text"  />
<p class="caption">
A caption
</p>

</div>

Which also create HTML, but I am not sure that this is supported by GFM renderer on Github

What should be the result ?

I believe we need to decide what should be fig.cap support with GFM as figure caption is not supported per-se on Github.

THank you

[dushoff]

Sorry for lack of context.

I was referring to @tamas-ferenci's comment that the output here is not the same as in the output: html_document context.

[cderv]

that the output here is not the same as in the output: html_document context.

Thank you that is helpful. With github_document(), the output is a markdown file (.md). But we also generate a HTML preview of the real output markdown, and aim is to make it closest to what it can be on Github - so it is not using html_document() in the background.

As Github Flavor Markdown rendered on Github does not seem to support caption, I believe we need to decide how it should be written in markdown, and then adapt the preview to match how it would rendered on Github.

At least that is my thinking

[SlowMo24]

GitLAB unfortunately does not nicely display figure captions, even if both alt and cap are supplied (https://github.com/rstudio/rmarkdown/issues/2385#issuecomment-1386745052). They look like normal text.

I used this lua-patch to at least make them italic.

function Div (img)
  if (img.attr.classes[1] =="figure") then
    img.content:insert(3,pandoc.RawBlock("html", "<i>"))
    img.content:insert(5,pandoc.RawBlock("html", "</i>"))
  end
  return img
end

note that the image is no longer an Image nor a Figure but a Div because its transformed to a raw HTML object.

Unfortunately I was unable to indent the captions because GitLAB seems to remove any style information in raw HTML. And I think its GitLABs and GitHUBs fault to not correctly render figure captions so I hope this is just a temporary workaround....