Adaptive syntax highlighting themes do not apply code block background colour

[mcanouil]

Bug description

When using an adaptive syntax highlighting theme name (e.g., syntax-highlighting: github), the code block background colour defined in the resolved .theme file is not applied. The $code-block-bg SCSS variable is never set, so code blocks inherit the Bootstrap theme's default background instead of the highlighting theme's background.

Using the explicit variant name (syntax-highlighting: github-light or syntax-highlighting: github-dark) works correctly because those names are not in the isAdaptiveTheme() list.

This means adaptive themes that define a background-color or editor-colors.BackgroundColor in their .theme files are effectively not supported: the background is silently discarded. This also breaks accessibility for those themes because the token colours were designed for a specific background colour to meet contrast requirements. When the background is discarded and replaced by an arbitrary Bootstrap theme background, the contrast ratios between syntax tokens and the code block background are no longer guaranteed, potentially failing WCAG guidelines.

7 out of 8 adaptive themes are affected:

Adaptive theme	Light variant background	Dark variant background
a11y	#fefefe	#2b2b2b
arrow	#f1f3f5	(none)
atom-one	(none)	(none)
ayu	#fafafa	#0a0e14
breeze	#ffffff	#232629
github	#ffffff	#24292e
gruvbox	#fbf1c7	#282828
monochrome	#ffffff	#000000

Only atom-one is unaffected (neither variant defines a background). arrow is partially affected (light variant has a background, dark does not).

Root cause

In src/format/html/format-html-scss.ts, the resolveTextHighlightingLayer() function guards background colour injection with !themeDescriptor.isAdaptive:

• quarto-cli/src/format/html/format-html-scss.ts

  Line 291 in 98be8a6

  if (themeDescriptor && !themeDescriptor.isAdaptive) {

if (themeDescriptor && !themeDescriptor.isAdaptive) {
  const backgroundColor = () => { /* ... */ };
  const background = backgroundColor();
  if (background) {
    layer.defaults = outputVariable(
      sassVariable("code-block-bg", asCssColor(background)),
      true,
    );
  }
  // ...
}

This guard was introduced in commit f6d2630 ("Explicit adaptive theme block support").

The theme file resolution in readHighlightingTheme() already correctly resolves the style-specific variant (e.g., github-light.theme for light mode, github-dark.theme for dark mode). Both files define background colours (editor-colors.BackgroundColor = #ffffff and background-color = #24292e respectively), but the !isAdaptive guard prevents those values from being used.

Steps to reproduce

Render the following three documents and compare the code block backgrounds in both light and dark mode:

• Document 1: Adaptive theme (github)

---
format:
  html:
    theme:
      light: flatly
      dark: cosmo
    syntax-highlighting: github
---

```r
print("Hello, Quarto!")
```

• Document 2: Explicit light variant (github-light)

---
format:
  html:
    theme:
      light: flatly
      dark: cosmo
    syntax-highlighting: github-light
---

```r
print("Hello, Quarto!")
```

• Document 3: Explicit dark variant (github-dark)

---
format:
  html:
    theme:
      light: flatly
      dark: cosmo
    syntax-highlighting: github-dark
---

```r
print("Hello, Quarto!")
```

Actual behavior

• Document 1 (github): code block background comes from the Bootstrap theme (flatly/cosmo), not from the github theme files.
• Document 2 (github-light): code block background is #ffffff (from github-light.theme).
• Document 3 (github-dark): code block background is #24292e (from github-dark.theme).

In light mode, Document 1 and Document 2 should look identical but do not (different code block background).
In dark mode, Document 1 and Document 3 should look identical but do not (different code block background).

The generated CSS for the adaptive theme (github) has no background-color on div.sourceCode, while the explicit variants do.

Expected behavior

syntax-highlighting: github should produce the same visual result as syntax-highlighting: github-light in light mode and syntax-highlighting: github-dark in dark mode, including the code block background colour.

Since resolveTextHighlightingLayer() is called separately for each style ("light" and "dark"), and readHighlightingTheme() already resolves the correct variant for each style, the $code-block-bg SCSS variable should be set from the resolved theme file regardless of whether the theme is adaptive.

Your environment

• IDE: VS Code
• OS: macOS 26.3

Quarto check output

Quarto 99.9.9
[✓] Checking environment information...
      Quarto cache location: /Users/mcanouil/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      commit: 6ecfc030bfcf381a37a925612b78e95876dcece2
      Path: /Users/mcanouil/Projects/quarto-dev/quarto-cli/package/dist/bin
[✓] Checking tools....................OK
      TinyTeX: v2026.02
[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/mcanouil/Library/TinyTeX/bin/universal-darwin
      Version: 2025
[✓] Checking basic markdown render....OK
[✓] Checking R installation...........OK
      Version: 4.5.2
      Path: /Library/Frameworks/R.framework/Resources
      knitr: 1.50
      rmarkdown: 2.30
[✓] Checking Knitr engine render......OK
[✓] Checking Python 3 installation....OK
      Version: 3.14.0
      Jupyter: 5.9.1
      Kernels: python3
[✓] Checking Jupyter engine render....OK

[mcanouil]

Dropping the guard (i.e., !themeDescriptor.isAdaptive) should be relatively safe:

The one thing to be aware of is the visual change for the default arrow theme (default theme).
Currently:

• arrow-light.theme defines background-color: #f1f3f5 (light grey) but it is discarded
• arrow-dark.theme defines no background

Removing the guard would cause arrow in light mode to start applying #f1f3f5 as $code-block-bg instead of deferring to the Bootstrap theme's default.
That is a visual change for the most common case.

I would also suggest setting a background colour for arrow-dark to ensure contrast does not fail WCAG depending on the bootstrap used which is currently the case.
In my opinion, for accessibility reasons, the guard should be removed and background colours added to both light and dark variants of atom-one, and background colour added to dark variant of arrow to ensure proper contrast.

---
format:
  html:
    theme:
      light: flatly
      dark: cosmo
    syntax-highlighting: arrow
---

```r
print("Hello, Quarto!")
```

---
format:
  html:
    theme:
      light: solar
      dark: morph
    syntax-highlighting: atom-one
---

```r
print("Hello, Quarto!")
```

The guard seems to be a workaround for the absence of background colour of arrow theme.