[accessibility] Use the table <caption> element

[rich-iannone]

Accessible data tables very often have brief descriptive text before or after the table that indicates the content of that table. This text should be associated to the table using the <caption> element.

The <caption> element needs to be the first thing after the opening <table> tag. The gt() function should have an argument (caption) for the user to insert a caption. If caption text isn’t provided then gt should generate caption text based on the table structure and use that in <caption>.

[jooyoungseo]

Maybe, could we use <caption> tag for title argument in the gt::tab_header()?

[rich-iannone]

I was just talking to Joe about this very thing. AFAIR, caption can be used for the header and the footer (note to self: don't use the deprecated align attribute, https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption).

[rich-iannone]

I see, so caption for title and something more generic for subtitle?

[jooyoungseo]

I thought, we may want to semantically bind <caption> to title either conditionally or always. But, I agree that title and caption could differ. (Personally, I think it is rare to find an example to include both title and caption and or caption is different from title). This is subject to further discussion.

[dmenne]

Any progress on caption and label? I am updating https://gist.github.com/dmenne/f8eb291c9e71a5de44764d442e8bdefd and wanted to include gt, but for lack of both (wrong?) I did not - these two are absolute requirements for scientific publication. kable is the yardstick - but it should be possible to put caption below the table. And numbered captions are more important than title.

I have referenced this thread now in the gist.

mcaption = function(label, caption){
  # Do not use underscores in label!
  stopifnot(length(grep("_", label)) == 0)
  cat("<caption>(#tab:", label, ")", caption, "</caption>", sep="")
}

[a-beretta]

I am trying to use the caption argument to do cross-referencing of tables in a Rmarkdown (bookdown::html_document2) file but it seems not working.

I use the following code (in the chunk's options I have r tab:table1, echo = FALSE)

df %>% gt(caption = "This is a caption")

Out of this chunk I'm using \@ref(tab:table1), but in the output instead of the table number I get ?? and the caption of the table is (#tab:tab:table1)This is a caption. In addition, in the terminal I have the warning: 1: The label(s) tab:table1 not found.

Am I doing something wrong or this is a bug ?

[dmenne]

My test case (works great, even if alignment has different defaults):

---
title: "Untitled"
format: html
---

## Quarto

```{r}
#| label: tbl-iris
#| tbl-cap: "Iris Data"
library(knitr)
kable(head(iris))
```


```{r}
#| label: tbl-iris1
#| tbl-cap: "Iris Data"
library(gt)
gt(head(iris))
```

As @tbl-iris and @tbl-iris1 show, flower tables can be beautiful.

[stevenbedrick]

This feature is working great in HTML output (thank you!), but has anybody managed to get it working with Word output, specifically via Bookdown's word_document2 output format? As best as I can tell, table captions are not making it into Word output at all, meaning that table cross-references are not functional. I've tried both tbl_caption as well as setting the Knitr tab.cap chunk option and neither seems to make it into the final Word output; however, knitting to HTML everything works the way it should.