Cross-referencing DT::datatable in bookdown

Question

I am trying to create a reference to DT::datatable in a bookdown project.

The bookdown manual states that (\#tab:label) should be placed at the beginning of the table caption. For testing, I created a new bookdown project in R-studio but replaced the contents of _output.yml with the following html_book configuration (I am only interested in HTML output).

bookdown::html_book:
    toc: yes
    theme: null
    highlight: pygments
    split_by: none

Then I added the following code at the bottom of 01-intro.Rmd.

```{r irisTab}
DT::datatable(iris, caption = '(\\#tab:irisTab) Iris table')
```

See Table \@ref(tab:irisTab).

My expectation was that (\\#tab:irisTab) would be replaced by Table 2.2 or at least 2.2 and the reference below would be 2.2. However, this does not work. The label remains verbatim and the reference is ??.

The closest I could get was by placing the caption text before the table.

Table (\#tab:irisTab): Iris table

```{r irisTab}
DT::datatable(iris)
```

See Table \@ref(tab:irisTab).

In that case, the reference works but the label (\#tab:irisTab) remains verbatim in the output, i.e. it is not replaced with 2.2 as expected.

Is there any way to create a DT table that would have a caption and could be referenced?

Update 1: @mikey-harper suggested using fig.cap. However, fig.cap updates only the fig counter and not the tab counter. Thus, if you have any non-DT tables, there will be multiple tables with the same number. It might be possible to treat all tables as figures. However, that would not be a standard approach. Typically, tables and figures have separate counters.

Saarinen

Answer 1

This issue has already been reported on GitHub: https://github.com/rstudio/bookdown/issues/313

Creating a Table caption for a DT:datatable within bookdown is not directly possible.

Explanation

HTML widgets like DT:datatable behave differently to the knitr:kable command which is typically used to create tables in bookdown. The Table caption will only be produced for a kable produced table, whilst all images/graphs/html outputs like this will not be labels as a table but as Figure.

Additional Problem

You are, however, also missing a key requirement for cross referencing, as explained here:

"Like figures, tables with captions will also be numbered and can be referenced."

Workaround

The best workaround is to treat the table as a figure, add a fig.cap to the chunk header and refer to it using \@ref(fig:chunk-name):

---
title: "Untitled"
output: bookdown::html_book
---

Table \@ref(fig:irisTab): Iris table

```{r irisTab, fig.cap="A table"}
DT::datatable(iris)
```

You will see this approach used in the bookdown book here by the package author: https://bookdown.org/yihui/bookdown/html-widgets.html. If it is good enough for Yihui, it is good enough for me.

Vilhelmina

Thanks for the suggestion. The problem with this approach is that it treats DT tables as figures, i.e. fig.cap updates the fig counter rather than the tab counter. I updated the question to relfect this problem. – Saarinen

Edited the answer to make it clearer that what you desire is not directly possible. If you display all your tables using DT then you will have a single list of Figures. – Vilhelmina

Answer 2

Since the last answer here in StackOverflow the GitHub Issue thread has continued and a solution which is useful - at least to me in bookdown::html_document2 - has emerged. For the sake of simplicity I will reproduce it here but it was ldecicco-USGS who originally wrote the chunk.

---
title: "Untitled"
site: bookdown::bookdown_site
output: bookdown::gitbook
documentclass: book
---

```{r myDThtmltools, results="asis", echo=FALSE}
library(DT)

datatable(head(iris))
    
cat("<table>", paste0("<caption>",
                      "(#tab:myDThtmltools)",
                      "caption",
                      "Here's my caption",
                      "</caption>"),
                      "</table>", sep ="\n")
```

Tab. \@ref(tab:myDThtmltools)

Tricostate