Render quarto to docx

[mollystevens-noaa]

ISSUES

• Document renders with tables and figures in the order that they're listed at the end of the document, not in the order that they're referenced

• Table headers not persistent across pages

  • This is a bug
    • Conflict between label: (required for referencing tables/figures) and wrapping headers
    • If you remove the label, the table headers carry over to the next page
  • Could have tables with persistent headers if referencing tables isn't required
  • Is it easier to rig a fix without the label: within the table with something like crossref, but would the table orders carry over?
  • Tried 'paged' df-print option (didn't work)

• @eeholmes worked on gt / flextable here https://github.com/eeholmes/TestBook

• Nuclear option: knit to pdf, open in docx using pandoc -- can command line .pdf -> .docx

  • Still requires manually moving edits over
  • Another option could be using trackdown package, but this requires reading/editing through markdown language, which some people aren't comfortable with
    • This package allows easy pull/push to Google docs
    • Tracks changes made in Google doc
    • Overwrites document after update() from (e.g.) RStudio up to google doc (doesn't track changes from Rstudio)
  • Or a combination of the 2 depending on the editor?
  • redoc is an archived package that worked with RMarkdown to pull edits between R/Word

Could add these as a feature request in the quarto repository

[ateucher]

Sidebar issue: In quarto, you can use shortcodes to include child documents, instead of code chunks with child = "..." (but then you also lose the ability to comment etc in the chunk)

[ateucher]

I added a comment to the bug report in Quarto.

The other issue, regarding ordering tables in the order that they referenced, would be a feature request I think.

[ateucher]

@mollystevens-noaa I think you mentioned that with latex/pdf output you can set it so that tables are printed at the end of the document in the order that they're referenced. Can you tell me how you set it up to do that? Is it in the top yaml?

[ateucher]

I did some digging around and found this quarto extension: iagopinal/figure-table-formatter, and had success with docx format, listing tables in the order in which they were referenced, and all aggregated at the end.

After installing in my project with:

quarto add iagopinal/figure-table-formatter

it is added to the _extensions directory.

Then this quarto document produced what I was looking for:

---
format: docx
filters:
  - iagopinal/figure-table-formatter
---

Blah blah ref @tbl:a, and then ref @tbl:b.

We reference @tbl:a again.

## Tables

```{r}
#| tbl-cap: "#tbl:b This should be the second table"
#| echo: false
data <- data.frame(ID = 1:10, Name = paste0("Name_", 1:10))

knitr::kable(data)
```

```{r}
#| tbl-cap: "#tbl:a This should be the first table"
#| echo: false
data <- data.frame(ID = 11:20, Name = paste0("Name_", 11:20))

knitr::kable(data)
```

&&&tbl&&&;

This issue opened by another user gives a pretty concise example.

A more comprehensive example is here.

A few things to note:

• the syntax is a bit different. Instead of using label in the chunk options, you use #| tbl-cap with a caption begininning with #tbl:label .... and in the text you reference it with @tbl:label.
• For me, the cross-references weren't clickable
• Using it with anything other than kable() (e.g., gt, flextable) resulted in weirdness - either duplicated table numbers, or no table numbers.

I don't think it's a perfect solution, but a good place to start I think!

[ateucher]

A bit more experimentation, this time with converting to pdf first, then to word. Pandoc can't convert from pdf, but it can (sometimes) convert from TeX, and it seems it can usually convert from the new typst format.

Starting with a qmd document like this (eg., called mydoc.qmd):

---
format:
  typst:
    keep-typ: true
---

<!-- set the typst environment to break figures/tables across pages -->
```{=typst}
#show figure: set block(breakable: true)
```

```{r}
#| label: tbl-1

data <- data.frame(ID = 1:50, Name = paste0("Name_", 1:50))

gt::gt(data)
```

<!-- 
you can end the table/figure breaking behaviour if needed:
```{=typst}
#set block(breakable: false)
```
-->

Creates a mydoc.pdf and a mydoc.typ file. We can convert the .typ to Word with pandoc:

pandoc -o mydoc.docx mydoc.typ

EDIT: For typst output, it appears that gt is better than flextable, as flextable produces the table as an image (embedded png), which is not ideal

[mollystevens-noaa]

Thank you so much for following up with this, @ateucher ! Unfortunately I don't have much time to troubleshoot the issue. I tried formatting my tables and using the package you referenced above, but I don't think it's installing properly.

The file installs in a different location, and I've tried moving it to the location listed here and restarting my computer. Should there be a .exe in this folder? I wonder if it's a permissions issue.

[ateucher]

Thanks @mollystevens-noaa, interesting that it installed to a different place for you than for me (in the _extensions folder).

There shouldn't be an .exe file, rather it uses the python file. Do you know if you have python installed on your computer?

[lisaailloud-NOAA]

I got the filter to work on my mac but when I try the same steps on my PC I get the error that @mollystevens-noaa got even with Python installed.

I'll keep troubleshooting...

[ateucher]

Thanks @lisaailloud-NOAA! I think it would be good to sort out the issues into core quarto, quarto extensions, and R packages so we know where to target our efforts. I'll try to summarize based on my understanding, then perhaps you and @mollystevens-noaa can help sort by priority?

[ateucher]

To summarize the main issues:

1. Formatting of tables when a label is used when rendering to docx:

   • table header is not repeated when table breaks across pages
   • gt formatting breaks
   • Quarto issues already open:
     • Flextable header is not repeated in each page for figures with captions quarto-dev/quarto-cli#11611
     • table cross references result in malformed xml quarto-dev/quarto-cli#10587

2. Collecting tables/figures at the end of a document, in the order in which they are referenced:

   • This filter gets close, but is a bit buggy. There are issues on Windows, using Python seems less than ideal.
   • A working extension would be great for this
   • But this also feels out of scope for Quarto core. It was mentioned in this discussion, and this one.
   • Could use the {{ < contents > }} shortcode to do it manually

3. Workflow for getting and incorporating feedback:

   • Currently using docx format so can use track changes and comments; this is what non-technical reviewers are used to.
   • {redoc} package development has been funded to address this
   • Would love to be able to get away from Word entirely, and still be able to incorporate reviews. Something like overleaf.
   • Other options: Render to pdf via LaTeX or typst, save source and collaborate on that. This still requires manual re-integration of changes back into source .qmd.

4. Tracking dependencies for reproducibility

   • Currently using renv, but that doesn't control quarto version so doesn't give total control. Have run into issues rendering to docx with different versions of Quarto.
   • Moving to cloud environment with docker containers, this should resolve much of this

[stefaniebutland]

June 10th, Carlos Scheidegger, Principal Engineer at Posit, started coming to coworking to work with folks to help with these advanced level needs.

These are docs on how to develop extensions: https://quarto.org/docs/extensions/creating.html .
List of publicly-available extensions: https://quarto.org/docs/extensions/