Add syntax-highlighting option for Pandoc 3.8 alignment

Pandoc 3.8 introduced --syntax-highlighting to replace --highlight-style.
This adds the new option to Quarto with support for:
- Style names (tango, github, etc.) for Pandoc skylighting
- Custom .theme files for KDE syntax themes
- "none" to disable highlighting
- "idiomatic" for native format highlighting (typst, LaTeX listings, reveal.js)

The deprecated highlight-style option remains supported but is hidden
from autocomplete. Typst format now supports all syntax highlighting
options including syntax-definitions for custom language definitions.

Fixes #13878

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: cderv

news/changelog-1.9.md

@@ -22,6 +22,10 @@ All changes included in 1.9:
 
 ## Formats
 
+### All Formats
+
+- ([#13878](https://github.com/quarto-dev/quarto-cli/issues/13878)): Add `syntax-highlighting` option replacing the deprecated `highlight-style` in Pandoc 3.8. It supports style names (e.g., `tango`, `github`), custom `.theme` files, `none` to disable highlighting, or `idiomatic` for native format highlighting. The `highlight-style` option remains supported but is deprecated.
+
 ### `gfm`
 
 - ([#13421](https://github.com/quarto-dev/quarto-cli/issues/13421)): Do not word-wrap titles in header.
@@ -56,7 +60,8 @@ All changes included in 1.9:
 - ([#13870](https://github.com/quarto-dev/quarto-cli/issues/13870)): Add support for `alt` attribute on cross-referenced equations for improved accessibility. (author: @mcanouil)
 - ([#13950](https://github.com/quarto-dev/quarto-cli/pull/13950)): Replace ctheorems with theorion package for theorem environments. Add `theorem-appearance` option to control styling: `simple` (default, classic LaTeX style), `fancy` (colored boxes with brand colors), `clouds` (rounded backgrounds), or `rainbow` (colored start border and colored title).
 - ([#13954](https://github.com/quarto-dev/quarto-cli/issues/13954)): Add support for Typst book projects via format extensions. Quarto now bundles the `orange-book` extension which provides a textbook-style format with chapter numbering, cross-references, and professional styling. Book projects with `format: typst` automatically use this extension.
-- ([#13978])(https://github.com/quarto-dev/quarto-cli/pull/13978)): Keep term and description together in definition lists to avoid breaking across pages. (author: @mcanouil)
+- ([#13978](https://github.com/quarto-dev/quarto-cli/pull/13978)): Keep term and description together in definition lists to avoid breaking across pages. (author: @mcanouil)
+- ([#13878](https://github.com/quarto-dev/quarto-cli/issues/13878)): Typst now uses Pandoc's skylighting for syntax highlighting by default (consistent with other formats). Use `syntax-highlighting: idiomatic` to opt-in to Typst's native syntax highlighting instead.
 
 ### `pdf`
 

src/command/render/pandoc.ts

@@ -99,6 +99,7 @@ import {
   kFormatResources,
   kFrom,
   kHighlightStyle,
+  kSyntaxHighlighting,
   kHtmlMathMethod,
   kIncludeAfterBody,
   kIncludeBeforeBody,
@@ -699,15 +700,18 @@ export async function runPandoc(
       printAllDefaults = mergeConfigs(extras.pandoc, printAllDefaults);
 
       // Special case - theme is resolved on extras and should override allDefaults
-      if (extras.pandoc[kHighlightStyle] === null) {
-        delete printAllDefaults[kHighlightStyle];
-        allDefaults[kHighlightStyle] = null;
-      } else if (extras.pandoc[kHighlightStyle]) {
-        delete printAllDefaults[kHighlightStyle];
-        allDefaults[kHighlightStyle] = extras.pandoc[kHighlightStyle];
+      // Clean up deprecated kHighlightStyle if user used old name
+      delete printAllDefaults[kHighlightStyle];
+      delete allDefaults[kHighlightStyle];
+      if (extras.pandoc[kSyntaxHighlighting] === null) {
+        delete printAllDefaults[kSyntaxHighlighting];
+        allDefaults[kSyntaxHighlighting] = null;
+      } else if (extras.pandoc[kSyntaxHighlighting]) {
+        delete printAllDefaults[kSyntaxHighlighting];
+        allDefaults[kSyntaxHighlighting] = extras.pandoc[kSyntaxHighlighting];
       } else {
-        delete printAllDefaults[kHighlightStyle];
-        delete allDefaults[kHighlightStyle];
+        delete printAllDefaults[kSyntaxHighlighting];
+        delete allDefaults[kSyntaxHighlighting];
       }
     }
 
@@ -1756,13 +1760,24 @@ function resolveTextHighlightStyle(
   } as FormatExtras;
 
   // Get the user selected theme or choose a default
-  const highlightTheme = pandoc[kHighlightStyle] || kDefaultHighlightStyle;
+  // Check both syntax-highlighting (new) and highlight-style (deprecated alias)
+  const highlightTheme = pandoc[kSyntaxHighlighting] ||
+    pandoc[kHighlightStyle] ||
+    kDefaultHighlightStyle;
   const textHighlightingMode = extras.html?.[kTextHighlightingMode];
 
   if (highlightTheme === "none") {
     // Disable highlighting - pass "none" string (not null, which Pandoc 3.8+ rejects)
     extras.pandoc = extras.pandoc || {};
-    extras.pandoc[kHighlightStyle] = "none";
+    extras.pandoc[kSyntaxHighlighting] = "none";
+    return extras;
+  }
+
+  if (highlightTheme === "idiomatic") {
+    // Use native format highlighting (typst, LaTeX listings, reveal.js highlight.js)
+    // Pass through to Pandoc 3.8+ which handles this natively
+    extras.pandoc = extras.pandoc || {};
+    extras.pandoc[kSyntaxHighlighting] = "idiomatic";
     return extras;
   }
 
@@ -1775,7 +1790,7 @@ function resolveTextHighlightStyle(
     case "dark":
       // Set light or dark mode as appropriate
       extras.pandoc = extras.pandoc || {};
-      extras.pandoc[kHighlightStyle] = textHighlightThemePath(
+      extras.pandoc[kSyntaxHighlighting] = textHighlightThemePath(
         inputDir,
         highlightTheme,
         textHighlightingMode,
@@ -1787,7 +1802,7 @@ function resolveTextHighlightStyle(
       // Clear the highlighting
       if (extras.pandoc) {
         extras.pandoc = extras.pandoc || {};
-        extras.pandoc[kHighlightStyle] = textHighlightThemePath(
+        extras.pandoc[kSyntaxHighlighting] = textHighlightThemePath(
           inputDir,
           "none",
         );
@@ -1797,7 +1812,7 @@ function resolveTextHighlightStyle(
     default:
       // Set the the light (default) highlighting mode
       extras.pandoc = extras.pandoc || {};
-      extras.pandoc[kHighlightStyle] =
+      extras.pandoc[kSyntaxHighlighting] =
         textHighlightThemePath(inputDir, highlightTheme, "light") ||
         highlightTheme;
       break;

src/config/constants.ts

@@ -543,7 +543,10 @@ export const kNumberDepth = "number-depth";
 export const kTopLevelDivision = "top-level-division";
 export const kPaperSize = "papersize";
 export const kLogFile = "log-file";
+// TODO: Deprecate kHighlightStyle in favor of kSyntaxHighlighting
+// Kept for backward compatibility with older documents using highlight-style
 export const kHighlightStyle = "highlight-style";
+export const kSyntaxHighlighting = "syntax-highlighting";
 export const kDefaultImageExtension = "default-image-extension";
 export const kLogo = "logo";
 export const kLinkColor = "linkcolor";
@@ -709,6 +712,7 @@ export const kPandocDefaultsKeys = [
   "ascii",
   kDefaultImageExtension,
   kHighlightStyle,
+  kSyntaxHighlighting,
   kSyntaxDefinitions,
   kSyntaxDefinition,
   kListings,

src/config/types.ts

@@ -93,6 +93,7 @@ import {
   kFreeze,
   kGladtex,
   kHighlightStyle,
+  kSyntaxHighlighting,
   kHtmlMathMethod,
   kHtmlPreTagProcessing,
   kHtmlTableProcessing,
@@ -594,6 +595,7 @@ export interface FormatPandoc {
   [kNumberSections]?: boolean;
   [kNumberOffset]?: number[];
   [kHighlightStyle]?: string | Record<string, string> | null;
+  [kSyntaxHighlighting]?: string | Record<string, string> | null;
   [kSectionDivs]?: boolean;
   [kHtmlMathMethod]?: string | { method: string; url: string };
   [kTopLevelDivision]?: string;

src/quarto-core/text-highlighting.ts

@@ -6,7 +6,7 @@
 import { join } from "../deno_ral/path.ts";
 
 import { kDefaultHighlightStyle } from "../command/render/constants.ts";
-import { kHighlightStyle } from "../config/constants.ts";
+import { kHighlightStyle, kSyntaxHighlighting } from "../config/constants.ts";
 import { FormatPandoc } from "../config/types.ts";
 
 import { existsSync } from "../deno_ral/fs.ts";
@@ -69,7 +69,10 @@ export function readHighlightingTheme(
   pandoc: FormatPandoc,
   style: "dark" | "light" | "default",
 ): ThemeDescriptor | undefined {
-  const theme = pandoc[kHighlightStyle] || kDefaultHighlightStyle;
+  // Check both syntax-highlighting (new) and highlight-style (deprecated alias)
+  const theme = pandoc[kSyntaxHighlighting] ||
+    pandoc[kHighlightStyle] ||
+    kDefaultHighlightStyle;
   if (theme) {
     const themeRaw = readTheme(inputDir, theme, style);
     if (themeRaw) {
@@ -86,12 +89,16 @@ export function readHighlightingTheme(
 }
 
 export function hasAdaptiveTheme(pandoc: FormatPandoc) {
-  const theme = pandoc[kHighlightStyle] || kDefaultHighlightStyle;
+  // Check both syntax-highlighting (new) and highlight-style (deprecated alias)
+  const theme = pandoc[kSyntaxHighlighting] ||
+    pandoc[kHighlightStyle] ||
+    kDefaultHighlightStyle;
   return theme && isAdaptiveTheme(theme);
 }
 
 export function hasTextHighlighting(pandoc: FormatPandoc): boolean {
-  const theme = pandoc[kHighlightStyle];
+  // Check both syntax-highlighting (new) and highlight-style (deprecated alias)
+  const theme = pandoc[kSyntaxHighlighting] ?? pandoc[kHighlightStyle];
   return theme !== null;
 }
 

src/resources/schema/document-code.yml

@@ -93,9 +93,9 @@
     long: |
       Specifies to apply a background color on code blocks. Provide a hex color to specify that the background color is
       enabled as well as the color of the background.
-- name: highlight-style
+- name: syntax-highlighting
   tags:
-    formats: [$html-all, docx, ms, $pdf-all]
+    formats: [$html-all, docx, ms, $pdf-all, typst]
   schema:
     anyOf:
       - object:
@@ -117,6 +117,7 @@
             - github
             - gruvbox
             - haddock
+            - idiomatic
             - kate
             - monochrome
             - monokai
@@ -135,21 +136,49 @@
     long: |
       Specifies the coloring style to be used in highlighted source code.
 
-      Instead of a *STYLE* name, a JSON file with extension
-      ` .theme` may be supplied.  This will be parsed as a KDE
-      syntax highlighting theme and (if valid) used as the
-      highlighting style.
+      Valid values:
+
+      - `none`: Disables syntax highlighting for code blocks.
+      - `idiomatic`: Uses the format's native syntax highlighter
+        (e.g., Typst's built-in highlighting, LaTeX `listings` package,
+        or reveal.js highlight.js plugin).
+      - A style name (e.g., `pygments`, `tango`, `github`): Uses
+        Pandoc's skylighting with the specified theme.
+      - A path to a `.theme` file: Uses a custom KDE syntax
+        highlighting theme.
+
+      For adaptive light/dark themes, specify an object with `light`
+      and `dark` properties pointing to theme files.
+
+- name: highlight-style
+  hidden: true
+  tags:
+    formats: [$html-all, docx, ms, $pdf-all, typst]
+  schema:
+    anyOf:
+      - object:
+          closed: true
+          properties:
+            light: path
+            dark: path
+      - string
+  description:
+    short: "Deprecated: use `syntax-highlighting` instead."
+    long: |
+      Deprecated: use `syntax-highlighting` instead.
+
+      Specifies the coloring style to be used in highlighted source code.
 
 - name: syntax-definition
   tags:
-    formats: [$html-all, docx, ms, $pdf-all]
+    formats: [$html-all, docx, ms, $pdf-all, typst]
   schema: path
   hidden: true
   description: "KDE language syntax definition file (XML)"
 
 - name: syntax-definitions
   tags:
-    formats: [$html-all, docx, ms, $pdf-all]
+    formats: [$html-all, docx, ms, $pdf-all, typst]
   schema:
     arrayOf: path
   description: "KDE language syntax definition files (XML)"