Quarto渲染PDF时kableExtra::kbl表格标题无法解析图/表引用的解决方法

问题说明 #

在Quarto中使用kableExtra::kbl()生成表格时，渲染为PDF格式时，表格标题中的交叉引用（如@fig-A）无法解析为正确的编号；但渲染为HTML时正常，且使用knitr::kable()生成的表格无此问题。需要保留kableExtra功能的同时修复该问题。

核心原因 #

kableExtra::kbl()默认会转义LaTeX特殊字符，导致Quarto的交叉引用标记被转义为普通文本，无法被LaTeX的引用系统识别解析。

解决方案 #

方法1：直接在kbl中设置标题并使用LaTeX原生引用 #

不在Quarto代码块的tbl-cap中设置标题，而是直接在kbl()的caption参数中定义标题，使用LaTeX原生的\ref{标签名}格式进行交叉引用，并开启escape = FALSE关闭转义：

#| echo: FALSE
#| label: tbl-kbl
#| tbl-cap: ""

kableExtra::kbl(
  d_mat,
  caption = "This is a table with `kableExtra::kbl()`. Compare with \\ref{fig-A}.",
  escape = FALSE
)

方法2：保留Quarto的tbl-cap设置，传递标题给kbl #

保留Quarto代码块的tbl-cap配置，通过knitr::opts_current$get()获取该标题，再传给kbl()并关闭转义，这样可以继续使用Quarto的@标签名格式：

#| echo: FALSE
#| label: tbl-kbl
#| tbl-cap: "This is a table with `kableExtra::kbl()`. Compare with @fig-A."

# 获取Quarto设置的表格标题
tbl_caption <- knitr::opts_current$get("tbl.cap")
kableExtra::kbl(
  d_mat,
  caption = tbl_caption,
  escape = FALSE
)

验证效果 #

使用上述任意方法后，渲染PDF时表格标题中的交叉引用会正确解析为对应的图/表编号，同时可以正常使用kableExtra的所有格式功能。

内容的提问来源于stack exchange，提问作者John K. Kruschke