Add citation rendering to kable() function

[mnneely]

Description

I just converted a large book chapter formerly in Word to Quarto because the publisher keeps destroying my Zotero citations with each revision, and I’m weary of re-doing almost 500 citations each time. It was a learning curve to say the least, but I did it.

One of my main problems is that I have dozens of tables in the chapter, most with citations in table cells of the form [@…], which are linked to a .bib file. These tables are in Excel, and I include them in the .qmd with R code to read from the Excel file, and generate a table with kable. Defining them directly in markdown is out of the question due to the number and size of them.

I can read them and Quarto will render the citations with kable, but because of the citations, I cannot process the table in any way with kableExtra, gt, flextable, or any other such tool. I learned that kable outputs markdown text which the Quarto engine can render to include the citations properly. However piping the output of kable to any of the other functions generates HTML output which will not render the citations. This leaves me with only the most basic formatted tables.

Can there be a solution to this? Can kable have an option to render the citations if a .bib is supplied so the output text can be parsed into formatted HTML in the usual fashion? This would be a pre-processing step prior to the full rendering of the document.

By the way, I tried the Word custom-reference-doc.docx option, and it didn’t work; kable outputs all tables in compact style, so there is no way I could find to style table rows (e.g. headers) differently than table body cells. Modifying the sample table in the reference doc to have a different header style was ignored.

[mcanouil]

You need to tell that the cell is a markdown cell (data-qmd), see for instance the trick being used for footnotes:

• Using footnotes in HTML tables #12869

This is documented in:

• https://quarto.org/docs/authoring/tables.html#html-tables

[mcanouil]

Here is the issue on knitr side to support this with kable():

• Make kable() compatible with Quarto when outputing HTML yihui/knitr#2289

[cscheid]

@mnneely Would you be willing to provide us with the source code for your chapter? It would make it easier for us to understand your workflow. You can also reach out to me in private if you would prefer that.

[cderv]

I think this could be useful so sharing here.

I have just added recently (so available in current dev version) some functions in quarto R 📦 to help use Markdown content in raw HTML produced by tools like kable() or kableExtra 📦

See vignette with some documentation: https://quarto-dev.github.io/quarto-r/articles/markdown-html-tables.html

I cannot process the table in any way with kableExtra, gt, flextable, or any other such tool.

In the vignette, I also show the package support for Quarto HTML table processing. Some tools, like gt or **tiny table **, support using citations in Markdown directly in the table.

Please do give a read to the vignette, and share feedback at https://github.com/quarto-dev/quarto-r for anything that should be clarified.

Quarto has support for Markdown in HTML table, but it requires some specific handling. The R function tbl_qmd_span() allows to create the right HTML raw content to insert in the HTML table for Quarto to parse it.

See example in the vignette. Release of the R package is soon to be, so giving it a try now insure I did not miss anything, and should cover your use case.

---

Example

---
title: "Citations in tables"
format: html
keep-md: true

references:
- type: article-journal
  id: Lovelace1842
  author:
  - family: Lovelace
    given: Augusta Ada
  issued:
    date-parts:
    - - 1842
  title: >-
    Sketch of the analytical engine invented by Charles Babbage, by LF Menabrea, 
    officer of the military engineers, with notes upon the memoir by the translator
  title-short: Molecular structure of nucleic acids
  container-title: Taylor’s Scientific Memoirs
  volume: 3
  page: 666-731
  language: en-GB
---

## Table with Citation

```{r}
tibble::tribble(
  ~Thing, ~Citation,
  1234, quarto::tbl_qmd_span("@Lovelace1842")
) |>
  knitr::kable(format = "html", escape = FALSE)
```

[mcanouil]

quarto::tbl_qmd_span()

Nice versatile helper function🤯

[mnneely]

I have just added recently (so available in current dev version) some functions in quarto R 📦

Thanks, I think this might do the trick. I realized after I posted that changing kable wouldn't work because it wouldn't be able to generate the formatted bibliography and the answer was likely in adding the ability for Quarto to render citations from html directly. All of the html styling packages just ignore the citations and leave them as [@...], so if Quarto can then recognize them in html, we are there.

However, if I understand, the new version would require all the citations in the source (in my case Excel table) to be embedded in tbl_qmd_span(). While feasible, it is an extra step, and how would it handle [@ref1; @ref2] for example tbl_qmd_span("[@ref1; @ref2]")? I think it would be easier if Quarto could recognize and process citations in html.

My work flow for this chapter was:

---
title: "Chapter"
format: docx
bibliography: my.bib
csl: my.csl
---

```{r}
df <- read_excel ("data.xlsx")
kable(df)
```

Inside the data.xlsx file, I had a cell with Text [@Ref1; @Ref2]. I can make some dummy files to help illustrate further.

[cderv]

I think it would be easier if Quarto could recognize and process citations in html.

The way for Quarto to process citation inserted as Markdown Syntax in HTML table is to provide them using the <span data-qmd or <span data-qmd-base64 attributes. all that the function tbl_qmd_span() does is creating this HTML string for your, while also doing the base64 encoding.

It makes you would have to add a processing step to your workflow to use this function on the cell.

---
title: "Chapter"
format: docx
bibliography: my.bib
csl: my.csl
---

```{r}
df <- read_excel ("data.xlsx")
# apply `tbl_qmd_span()` on the cells in your df
new_df <- mark_markdown(df, "col_markdown")
kable(new_df, escape = FALSE)
```

All of the html styling packages just ignore the citations and leave them as [@...], so if Quarto can then recognize them in html, we are there.

See the vignette I wrote to understand the status of table package regarding this feature. tbl_qmd_span is only required for package that does not already support (1) identifying cell or column with Markdown content to process (2) write the <span> for the user.

See https://quarto-dev.github.io/quarto-r/articles/markdown-html-tables.html

I think it would be easier if Quarto could recognize and process citations in html.

Recognizing Markdown in a raw HTML table is not something that can be done at the Quarto level. This is not compatible with some other feature that makes HTML table parsing output for many formats. It is also quite time-consuming in resources to always have Pandoc trying to detect "Is this markdown in HTML ?"

So there may be a mode where you (1) opt out HTML table processing in Quarto, (2) don't use raw HTML content, and insert HTML in the body without ```{=html}. However, I would highly discourage this as some features will be lost, and it could have a bad side effect.

We think our system is more targeted: Mark which content needs to be parsed as Markdown. Then Quarto does the rendering by extracting from the HTML table.

Tools like gt or tinytable already integrate with this idea. See the vignette.

Hope it helps understand. I am happy to look further at your use case with the xlsx file if you provide a reproducible example (as a github repo for example)

---

Regarding your ref1 / ref2 question

Let's try !

---
title: "Citations in tables"
format: html
keep-md: true

references:
- type: article-journal
  id: ref1
  author:
  - family: Lovelace
    given: Augusta Ada
  issued:
    date-parts:
    - - 1842
  title: >-
    Sketch of the analytical engine invented by Charles Babbage, by LF Menabrea, 
    officer of the military engineers, with notes upon the memoir by the translator
  title-short: Molecular structure of nucleic acids
  container-title: Taylor’s Scientific Memoirs
  volume: 3
  page: 666-731
  language: en-GB
- type: article-journal
  id: ref2
  author:
  - family: Lovelace
    given: Augusta Ada
  issued:
    date-parts:
    - - 1842
  title: >-
    Other one 
  volume: 4
  page: 666-731
  language: en-GB
---

## Table with Citation

```{r}
tibble::tribble(
  ~Thing, ~Citation,
  1234, quarto::tbl_qmd_span("[@ref1;@ref2]")
) |>
  knitr::kable(format = "html", escape = FALSE)
```

As you can see it works as expected because using tbl_qmd_span() (or directly <span data-qmd-*) is the way to tell Quarto this cell needs to be processed as Markdown like the rest of the body

[mnneely]

Thanks a lot for the help. I read the vignettes. Seems like this will work. I've made a repository containing example files to illustrate the workflow I'm trying to use. I'm not sure how to use the dev version of Quarto, and I assume the mark_markdown() is a placeholder in your code above, so I included a comment on that. Having a function to inject the tbl_qmd_span() around all citations will make life easier indeed!

[cderv]

Having a function to inject the tbl_qmd_span() around all citations will make life easier indeed!

I think this is matter of lapply(), vapply(), or similar (or purrr::map function if you're a tidyverse user).

I have though of doing it in quarto R, but it feels too specifig to cover everything. I would be for kableExtra to support something like this, like gt or tinytable package do.

Here is an example with math

---
title: "kableExtra"
format: html
execute: 
  echo: false
---

## Quarto

```{r}
library(kableExtra) 

tbl1 <- data.frame(
     var = c("$a$", "$b$", "$c$"),
     val = c(1, 2, 3)
   )
```

```{r}
# wrap in syntax for quarto using dev quarto function
tbl1$var <- vapply(tbl1$var, quarto::tbl_qmd_span, character(1))
```

```{r}
kbl(tbl1, format="html", escape = FALSE) %>%
  kable_classic(full_width = F) %>%
    kable_styling(font_size = 24) %>%
      row_spec(2, color = "lightgray", background = "darkred")

```