tcolorbox LaTeX package causes error when using Quarto code cell shading

[maxdrohde]

Bug description

When I import the tcolorbox LaTeX package into Quarto, I get an error if I am also using the code block background color YAML argument (code-block-bg). Please see the minimal example below.

Steps to reproduce

Minimal document showing the error

---
title: "Bug test"
format:
  pdf:
    code-block-bg: "#f1f3f5"
    include-in-header: 
      text: |
        \usepackage{tcolorbox}
---

```{r}
1+1

### Expected behavior

_No response_

### Actual behavior

### Error log

pandoc to: latex output-file: bug_test.tex standalone: true pdf-engine: xelatex variables: graphics: true tables: true default-image-extension: pdf

metadata documentclass: scrartcl classoption:

• DIV=11
• numbers=noendperiod papersize: letter header-includes:
• '\KOMAoption{captions}{tableheading}' block-headings: true title: Bug test code-block-bg: '#f1f3f5'

running xelatex - 1 This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex) restricted \write18 enabled. entering extended mode

updating tlmgr

updating existing packages

compilation failed- error Package pgfkeys Error: I do not know the key '/tcb/frame hidden' and I am goi ng to ignore it. Perhaps you misspelled it.

See the pgfkeys package documentation for explanation. Type H for immediate help. ...

l.200 \begin{Shaded}

see bug_test.log for more information.

### Your environment

- OS: MacOS Ventura 13.5.2 (22G91)

### Quarto check output

```bash
❯ quarto check

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.1: OK
      Dart Sass version 1.55.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.3.450
      Path: /Applications/quarto/bin

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

[✓] Checking Python 3 installation....OK
      Version: 3.11.3
      Path: /Library/Frameworks/Python.framework/Versions/3.11/bin/python3
      Jupyter: 5.3.0
      Kernels: ir, julia-1.6, julia-1.8, julia-1.9, juliapro_v1.5.0-1-1.5, julia-1.5, julia-12-threads-1.8, python3

(|) Checking Jupyter engine render....0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.2.1
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Library/Frameworks/R.framework/Versions/4.2/Resources/library
      knitr: 1.43
      rmarkdown: 2.23

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

[cscheid]

Thanks for the report. I'm not sure what you expect Quarto to do here. In general, not every latex package is compatible with other LaTeX package. You probably need to make changes to the template to accommodate your use case.

[maxdrohde]

Thanks @cscheid, it was just surprising to me that the Quarto code block background option for PDFs wasn't compatible with a common LaTeX package. I see your point though -- maybe this is more of an issue with the tcolorbox package. If there was a way to change the Quarto implementation so that they don't conflict, that would be helpful to me, but I realize that might be challenging. I was just stumped for a while figuring out where the error was coming from.

[cscheid]

If there was a way to change the Quarto implementation, that would be helpful so that they don't conflict.

We don't change the Pandoc format templates unless it's absolutely necessary, because the additional confusion from the inconsistency tends to cause more problems than it solves.

I see your point though -- maybe this is more of an issue with the tcolorbox package.

It's likely that this package is not compatible with some other package used in the latex template. I recommend you use keep-tex: true (or quarto render file.qmd --to latex), inspect the generated source, and debug it from there. That will tell you how to change the templates as necessary.

[dragonstyle]

Quarto uses the tcolorbox package to implement code cell shading, so you should be able to just omit the \usepackage{tcolorbox} in this case...

[cscheid]

So the issue is probably that the include means that the packages are included in the wrong order, and that's the error message that LaTeX emits... yikes. 👀 Typst cannot win soon enough!

[cderv]

I believe the issue is because Quarto is loading some packages with options

\@ifpackageloaded{tcolorbox}{}{\usepackage[skins,breakable]{tcolorbox}}

https://github.com/quarto-dev/quarto-cli/blob/aadb1908193ec91ef48448e3a89eba3efe0bcf20/src/resources/filters/layout/meta.lua#L41

But with ifpackageloaded, we do that only when package is not already loaded. When \usepackage{tcolorbox} is used in YAML, it is loaded before our call.

This means options are not added.... but we need them for the background it seems. This leads to the error.

Doing this don't have issue.

    include-in-header: 
      text: |
        \usepackage[skins,breakable]{tcolorbox}

If we wanted to be really clean with the option we need, the usual way is to use \PassOptionsToPackages at the top of the document. This will define some option to set when the package is loaded. We could then load tcolorbox if not already loaded. This is explain in https://tex.stackexchange.com/a/124052/209358 a bit, and this is what Pandoc is doing in its template https://github.com/quarto-dev/quarto-cli/blob/aadb1908193ec91ef48448e3a89eba3efe0bcf20/src/resources/formats/pdf/pandoc/latex.template#L1-L9

Anyhow, another LaTeX weirdness. Not loading a package already loaded in template is usually a good approach.