Captions & crossrefs not rendering in Quarto with Flextable

[leeroyaus]

Bug description

Description

When rendered via Quarto with output format as docx, caption (tbl-cap) and crossref (@tbl-ref) not working with flextable.

Reproducible example

---
title: Flextable in Word
format: docx
---

# Tables

Reference @tbl-flextable

```{r}
#| label: tbl-flextable
#| tbl-cap: "Caption 2"
library(flextable)
flextable(head(mtcars))
```

See output docx file: mwe_book.docx

This issue is also mentioned here on flextable github page: flextable Github page

Expected result

Caption and crossref should render correctly in Word doc

RStudio information

$long_version
[1] "2022.02.3+492"

$release_name
[1] "Prairie Trillium"

OS information

Windows 10 Enterprise

quarto check Output

[>] Checking Quarto installation......OK
      Version: 0.9.649
      Path: C:\Program Files\Quarto\bin\
      CodePage: 1252

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking R installation...........OK
      Version: 4.2.0
      Path: C:/PROGRA~1/R/R-42~1.0
      LibPaths:
        - C:/Users/username/Documents/R/win-library/4.2
        - C:/Program Files/R/R-4.2.0/library
      rmarkdown: 2.14

[>] Checking Knitr engine render......OK

quarto tools check Output

[>] Inspecting tools

Tool         Status                    Installed     Latest  
chromium     Not installed             ---           869685  
tinytex      External Installation     ---           v2022.07

Checklist

• formatted your issue so it is easier for us to read?
• included a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• documented the quarto version you're running, by pasting the output from running quarto check in the "Quarto Check Output" text area?
• documented the version of the quarto tools you're running, by providing the output from running quarto tools check in the "Quarto Tools Check Output" text area?
• documented the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• documented which operating system you're running? If on Linux, please provide the specific distribution as well.
• upgraded to the latest version, including your versions of R, the RStudio IDE, and relevant R packages?

[eeholmes]

I see the same problem with flextable for PDF output also.

Example on RStudio Cloud https://rstudio.cloud/content/4327822

A similar problem appears with {gt} in PDF. But in this case the caption appears but the Table 1 part does not. It looks ok in Word however.

---
title: "test"
format: 
  pdf: default
  html: default
  docx: default
---

# flextable

Reference @tbl-flextable

```{r}
#| label: tbl-flextable
#| tbl-cap: "Caption 1"
library(flextable)
flextable(head(mtcars))
```

# gt

Reference @tbl-gt

```{r}
#| label: tbl-gt
#| tbl-cap: "Caption 2"
library(gt)
gt(head(mtcars[,1:3]))
```

RStudio version on cloud is 2022.02.2 but I see the same problem on my laptop (M1 Mac) with RStudio 2022.07.1+554

[jjallaire]

The problem is that flextable is creating raw openxml output for the table which Quarto doesn't know how to parse/interact with (we can do this for raw HTML and raw LaTeX just not raw openxml.

A possible solution would be to fallback to a div which contains the table and just implements the caption manually (i.e. not actually the openxml table caption but just text appearing above or below). We'll take a look at doing this for our v1.2 release.

[eeholmes]

Ah right. That's why flextable works so nicely with Word; it creates raw openxml.

[bd-karen-byron]

I'm hoping any caption/crossref solution includes making the auto-numbering work as well
thanks

[davidgohel]

Most of the issues should be now fixed for flextable and quarto (in the github version). The limit for now is in the docx version. There is no caption generated by Quarto as explained upper. flextable manages it but as a result, cross-referencing is not possible with the syntax (@tbl-dudu). If there is a solution later, I will adapt the code. As a workaround, use officer::run_reference() and make sure officedown is loaded (to automatically trigger OOXML printing).

---
title: "Untitled"
format: docx
---

```{r include=FALSE}
library(officer)
library(officedown)
knitr::opts_chunk$set(echo = FALSE)
```


blah blah blah `r run_reference(id = "tbl-flextable")`.

```{r}
#| label: tbl-flextable
#| tbl-cap: Caption **strong**
flextable::flextable(mtcars[1:4, 1:4])
```

The HTML code can contain a caption, but it will be rewritten by Quarto with the values of the R chunk parameters, same for the PDF version. I think that Quarto's support imposes to prefer the values linked to the captions defined in the chunk options rather than the values defined with set_caption. I don't have control over the values taken in HTML and PDF, it then seems quite natural to adapt the DOCX behavior (which is not modified by Quarto) to the Quarto behavior, i.e. to prefer the parameters defined in the R chunk. Thanks for telling me if I've misunderstood something, and I'll try to correct my code. With 'R Markdown' documents, it's always the opposite, so I first wanted to implement the same logic for consistency but it proved impossible.

[eeholmes]

That's too bad re docx output. For my agency (NOAA), we use flextable because it works so well with docx. I have not found another table generating package that works as seamlessly, meaning looks good by default. For PDF and HTML, there are a number of other good table generating packages.

Any sense of which table package that Quarto will best support going forward? Given that supporting every package out there might be untenable?

Which table package doesn't matter so much, rather it is the cross-format support that is key: looks equally good in HTML, PDF and docx (without changing the table code) and cross-refs/captions work across all formats. Fancy table widgets and formatting (colors and stripes stuff) is not important. Just need solid scientific table support (captions, footnootes, footer notes, landscape option (docx and PDF), and reasonable auto-scaling and table breaking across pages (docx and PDF).

[jjallaire]

We will certainly try to maintain strong support for all popular table package. In addition, we are investing aggressively in the gt package (in fact its maintainer @rich-iannone has recently joined the Quarto team to focus on among other things gt and tables more broadly in the Quarto ecosystem).

[eeholmes]

Good to know re {gt} package. We (NOAA R users admins) have talked about encouraging a switch to {gt}. But last info I saw (June? 22) https://www.danieldsjoberg.com/gtsummary/articles/rmarkdown.html was that {gt} still not fully supporting docx. Then again, that's from the {gtsummary} vignette not {gt}.

[cscheid]

docx output in gt main was merged on July 5th rstudio/gt#962, and will make to the next point release coming up in about 2 weeks.

[shafayetShafee]

@cscheid , does that mean if I install the development version of {gt} right now, I can use {gt} for docx output in quarto?

[cscheid]

Yes:

---
title: docx test
format: docx
---

## docx support in quarto

```{r}
library(gt)
exibble %>% gt()
```

[cscheid]

I'm going to push a full fix for this to 1.3, since we'll be adding native AST types for tables, etc. and we should start working on communicating better with downstream libraries.

[kjell-stattenacity]

I was able to compile a Word document using Quarto with one flextable. However, the rendering hangs when I add a second flextable (see example below). I'm working with the most recent development version of Quarto, and RStudio (2022.07.1) and flextable (flextable_0.8.3.012) are up-to-date.

---
title: "Untitled"
format: docx
---

```{r include=FALSE}
library(officer)
library(officedown)
library(flextable)
knitr::opts_chunk$set(echo = FALSE)
```

 Table `r run_reference(id = "tbl-flextable")` works fine.

```{r}
#| label: tbl-flextable
#| tbl-cap: First Flextable
flextable::flextable(mtcars[1:4, 1:4])
```

However, the rendering hangs for a second table (Table `r run_reference(id = "tbl-flextable2")`). 

```{r}
#| label: tbl-flextable2
#| tbl-cap: Second Flextable
flextable::flextable(mtcars[1:4, 1:4])
```

[cscheid]

@kjell-stattenacity I can reproduce that locally, and that's different, it's actually a bug. Thanks for the report! I'll open a separate issue.

[davidgohel]

I think this issue is fixed in flextable since few months. Can this issue be closed?

[cscheid]

@davidgohel your previous message said this:

The limit for now is in the docx version. There is no caption generated by Quarto as explained upper. flextable manages it but as a result, cross-referencing is not possible with the syntax (@tbl-dudu). If there is a solution later, I will adapt the code. As a workaround, use officer::run_reference() and make sure officedown is loaded (to automatically trigger OOXML printing)

I would prefer to keep this issue open so that we can handle the crossref syntax issue better on quarto's end.

[davidgohel]

@cscheid OK, thanks. I'd like to have the same behavior as with the other formats. If I should change something with captions in Word for Quarto, let me know (I don't know if I did the right thing!)

[schwa021]

r run_reference(id = "tbl-flextable")

@cscheid , does that mean if I install the development version of {gt} right now, I can use {gt} for docx output in quarto?

You can produce tables, but, unfortunately, you can't format them

see this issue

Hopefully soon?

[sgvignali]

Hi all, is there any update for flextable and word output?

[cscheid]

@sgvignali we're going to do this work in 1.4, as I indicated on the milestone change.

[cderv]

For reference to follow work across repo, this is also tracked in flextable directly at davidgohel/flextable#494

[aaronschiff]

@davidgohel I don't think the workaround you gave above works any more? Here's the Word output I get from the same code with Quarto 1.3.333, Flextable 0.9.1, Officer 0.6.2 and Officedown 0.3.0. It seems to copy the entire table where the cross-reference should be and there are issues with the table captions.

[BMC1986]

@davidgohel I don't think the workaround you gave above works any more? Here's the Word output I get from the same code with Quarto 1.3.333, Flextable 0.9.1, Officer 0.6.2 and Officedown 0.3.0. It seems to copy the entire table where the cross-reference should be and there are issues with the table captions.

Hi @aaronschiff, did you come up with a work-around for this one? I have the same issue.

[aaronschiff]

@BMC1986 no I didn't, sorry. For now I had to stop producing Word output and wait for a future fix in Quarto. PDF output works fine so I am using that in the meantime.

[ldecicco-USGS]

Just to clarify, neither flextable nor gt can currently handle cross-referencing in Word, correct? We're waiting on a Quarto update?

That is what I'm noticing but want to make sure I haven't missed a workaround. The only way I can seem to get any table cross-referencing in Word is knitr::kable or printing raw markdown with result: as-is.

[schwa021]

Just to clarify, neither flextable nor gt can currently handle cross-referencing in Word, correct? We're waiting on a Quarto update?

That is what I'm noticing but want to make sure I haven't missed a workaround. The only way I can seem to get any table cross-referencing in Word is knitr::kable or printing raw markdown with result: as-is.

Any progress on this? The gt documentation suggests it works - but it definitely doesn't for me.

[mcanouil]

@schwa021 since the issue here is really about flex table, please open a new GitHub Discussion with a "working" reproducible example.
(This is to avoid cluttering/diluting this issue).

To note, flextable/gt do a lot of processing and do not output markdown which basically disable some markdown-based feature.
Note also that the goal of those two R packages is to style table thus output something that is not markdown (the output depends on the format).

[cscheid]

With the current 1.4 prereleases, the following almost works.

---
title: Flextable in Word
format: docx
---

# Tables

Reference @tbl-flextable

```{r}
#| label: tbl-flextable
#| tbl-cap: "Caption 2"
library(flextable)
flextable(head(mtcars))
```

Produces a document that Microsoft Word doesn't appear to like. But if you tell it to try to open the file anyway, you should see this:

The remaining issue with Microsoft Word will be handled on #7321.