quarto-dev · cderv · Feb 6, 2026 · Feb 6, 2026 · Feb 6, 2026 · Feb 6, 2026
diff --git a/docs/books/book-output.qmd b/docs/books/book-output.qmd
@@ -13,19 +13,19 @@ If you want to specify rendering options (including format-specific options), yo
 Here's an example configuration:
 
 ``` yaml
-highlight-style: pygments
+syntax-highlighting: pygments
 
 format:
   html:
     theme: cosmo
     code-copy: true
   pdf: default
-    
+
 bibliography: references.bib
 csl: citestyle.csl
 ```
 
-Note that in the above configuration the `highlight-style` option applies to all formats whereas the `html` options apply to only HTML output. The bibliography related options naturally also apply to all formats.
+Note that in the above configuration the `syntax-highlighting` option applies to all formats whereas the `html` options apply to only HTML output. The bibliography related options naturally also apply to all formats.
 
 ## Reader Tools
 

diff --git a/docs/get-started/authoring/_authoring-complete.qmd b/docs/get-started/authoring/_authoring-complete.qmd
@@ -3,7 +3,7 @@ title: "Housing Prices"
 author: "Mine Çetinkaya-Rundel"
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 format:
   html: 
     code-fold: true

diff --git a/docs/get-started/authoring/_text-editor.md b/docs/get-started/authoring/_text-editor.md
@@ -70,7 +70,7 @@ title: "Quarto Document"
 author: "Norah Jones"
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 format: 
   pdf: 
     geometry: 
@@ -95,7 +95,7 @@ The next three lines are document format options that *apply to all formats*. wh
 ``` yaml
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 ```
 
 Next, we have the `format` option, where we provide format-specific options.

diff --git a/docs/get-started/authoring/jupyter.qmd b/docs/get-started/authoring/jupyter.qmd
@@ -69,7 +69,7 @@ title: "Quarto Document"
 author: "Norah Jones"
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 format: 
   html: 
     code-fold: true
@@ -100,7 +100,7 @@ which is why they are specified at the root level.
 ``` yaml
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 ```
 
 Next, we have the `format` option, where we provide format-specific options.

diff --git a/docs/get-started/authoring/rstudio.qmd b/docs/get-started/authoring/rstudio.qmd
@@ -105,7 +105,7 @@ Let's add the `html` and `docx` formats to our document and modify some options
 ---
 title: "Housing Prices"
 author: "Mine Çetinkaya-Rundel"
-highlight-style: pygments
+syntax-highlighting: pygments
 format:
   html: 
     code-fold: true
@@ -133,7 +133,7 @@ The next line is a document format option that *applies to all formats*, which i
 
 ``` yaml
 ---
-highlight-style: pygments
+syntax-highlighting: pygments
 ---
 ```
 
@@ -199,7 +199,7 @@ title: "Housing Prices"
 author: "Mine Çetinkaya-Rundel"
 toc: true
 number-sections: true
-highlight-style: pygments
+syntax-highlighting: pygments
 format:
   html: 
     code-fold: true

diff --git a/docs/output-formats/_document-options-section-numbering.md b/docs/output-formats/_document-options-section-numbering.md
@@ -17,3 +17,15 @@ To exclude an individual heading from numbering, add the `.unnumbered` class to
 ``` markdown
 ### More Options {.unnumbered}
 ```
+
+::: {.content-visible when-meta="doc-type.typst"}
+You can also customize the display of the section numbers with the `section-numbering` YAML option. This option expects a string that describes the numbering schema. For example, the following schema describes numbering sections with numerals, subsection with uppercase letters, and subsubsections with lower case letters, using `.` as a separator:
+
+```yaml
+---
+section-numbering: 1.A.a
+---
+```
+
+You can read more about specifying the numbering schema in the [Typst documentation for numbering](https://typst.app//docs/reference/model/numbering#parameters-numbering).
+:::
diff --git a/docs/output-formats/_document-options-syntax-highlighting.md b/docs/output-formats/_document-options-syntax-highlighting.md
@@ -10,14 +10,31 @@ Pandoc will automatically highlight syntax in [fenced code blocks](https://pando
 
 Pandoc can provide syntax highlighting for over 140 different languages (see the output of `quarto pandoc --list-highlight-languages` for a list of all of them). If you want to provide the appearance of a highlighted code block for a language not supported, just use `default` as the language name.
 
-You can specify the code highlighting style using `highlight-style` and specifying one of the supported themes. Supported themes include: arrow, pygments, tango, espresso, zenburn, kate, monochrome, breezedark, haddock, atom-one, ayu, breeze, dracula, github, gruvbox, monokai, nord, oblivion, printing, radical, solarized, and vim.
+You can specify the code highlighting style using `syntax-highlighting` and specifying one of the supported themes. Supported themes include: a11y, arrow, pygments, tango, espresso, zenburn, kate, monochrome, breezedark, haddock, atom-one, ayu, breeze, dracula, github, gruvbox, monokai, nord, oblivion, printing, radical, solarized, and vim.
 
 For example:
 
 ``` yaml
-highlight-style: github
+syntax-highlighting: github
 ```
 
+In addition to theme names, `syntax-highlighting` accepts two special values:
+
+- `none` --- disables syntax highlighting entirely.
+- `idiomatic` --- delegates highlighting to the output format's native system instead of Pandoc's built-in Skylighting engine. For LaTeX, this uses the `listings` package; for Typst, this uses Typst's built-in code highlighting. See each format's documentation for details.
+
+::: {.content-visible when-meta="doc-type.pdf"}
+For LaTeX/PDF output, `syntax-highlighting: idiomatic` uses the LaTeX `listings` package for code highlighting instead of Pandoc's default approach (which uses `fancyvrb` with `\Shaded`/`\Highlighting` environments). This may be preferred when working with LaTeX templates or publishers that expect `listings`-based code blocks.
+:::
+
+::: {.content-visible when-meta="doc-type.typst"}
+By default, Typst output uses Pandoc's Skylighting engine for syntax highlighting, with the same themes available as other formats (e.g. HTML, PDF).
+
+Setting `syntax-highlighting: idiomatic` delegates highlighting to Typst's built-in code highlighting. In this mode, Typst receives plain fenced code blocks and applies its own styling. This may be preferred when using custom Typst templates that style code blocks.
+
+Setting `syntax-highlighting: none` disables all highlighting, producing unstyled code blocks.
+:::
+
 Highlighting themes can provide either a single highlighting definition or two definitions, one optimized for a light colored background and another optimized for a dark color background. When available, Quarto will automatically select the appropriate style based upon the code chunk background color's darkness. You may always opt to specify the full name (e.g. `atom-one-dark`) to bypass this automatic behavior.
 
 By default, code is highlighted using the `arrow` theme, which is optimized for accessibility. Here are examples of the `arrow` light and dark themes:

diff --git a/docs/output-formats/_document-options-toc.md b/docs/output-formats/_document-options-toc.md
@@ -17,4 +17,12 @@ If you want to exclude a heading from the table of contents, add both the `.unnu
 
 ``` markdown
 ### More Options {.unnumbered .unlisted}
-```
+```
+
+::: {.content-visible when-meta="doc-type.typst"}
+The `toc-indent` option controls how far entries are indented in the displayed table of contents. The default is equivalent to:
+
+```{.yaml}
+toc-indent: 1.5em
+```
+:::
diff --git a/docs/output-formats/html-code.qmd b/docs/output-formats/html-code.qmd
@@ -235,7 +235,7 @@ Pandoc will automatically highlight syntax in [fenced code blocks](https://pando
 
 Pandoc can provide syntax highlighting for over 140 different languages (see the output of `quarto pandoc --list-highlight-languages` for a list of all of them). If you want to provide the appearance of a highlighted code block for a language not supported, just use `default` as the language name.
 
-You can specify the code highlighting style using `highlight-style` and specifying one of the supported themes. These themes are "adaptive", which means they will automatically switch between a dark and light mode based upon the theme of the website. These are designed to work well with sites that include a dark and light mode.
+You can specify the code highlighting style using `syntax-highlighting` and specifying one of the supported themes. These themes are "adaptive", which means they will automatically switch between a dark and light mode based upon the theme of the website. These are designed to work well with sites that include a dark and light mode.
 
 -   a11y
 -   arrow
@@ -267,10 +267,10 @@ As well as an additional set of extended themes, including:
 -   solarized
 -   vim-dark
 
-The `highlight-style` option determines which theme is used. For example:
+The `syntax-highlighting` option determines which theme is used. For example:
 
 ``` yaml
-highlight-style: github
+syntax-highlighting: github
 ```
 
 Highlighting themes can provide either a single highlighting definition or two definitions, one optimized for a light colored background and another optimized for a dark color background. When available, Quarto will automatically select the appropriate style based upon the code chunk background color's darkness. Users may always opt to specify the full name (e.g. `atom-one-dark`) to by pass this automatic behavior.
@@ -281,19 +281,19 @@ Examples of the light and dark themes:
 
 #### Arrow (light)
 
-![](images/arrow.png){fig.alt="A block of code showcasing the Arrow (light) theme."}
+![](images/arrow.png){fig-alt="A block of code showcasing the Arrow (light) theme."}
 
 #### Arrow (dark)
 
-![](images/arrow-dark.png){fig.alt="A block of code showcasing the Arrow (dark) theme."}
+![](images/arrow-dark.png){fig-alt="A block of code showcasing the Arrow (dark) theme."}
 
 #### Ayu (light)
 
-![](images/ayu.png){fig.alt="A block of code showcasing the Ayu (light) theme."}
+![](images/ayu.png){fig-alt="A block of code showcasing the Ayu (light) theme."}
 
 #### Ayu (dark)
 
-![](images/ayu-dark.png){.preview-image fig.alt="A block of code showcasing the Ayu (dark) theme."}
+![](images/ayu-dark.png){.preview-image fig-alt="A block of code showcasing the Ayu (dark) theme."}
 
 ### Custom Highlighting
 
@@ -303,21 +303,21 @@ For example:
 
 ``` yaml
 ---
-highlight-style: custom.theme
+syntax-highlighting: custom.theme
 ---
 ```
 
 In addition, if you'd like to provide adaptive themes, you may also pass both a light and dark theme file:
 
 ``` yaml
 ---
-highlight-style:
+syntax-highlighting:
   light: custom-light.theme
   dark: custom-dark.theme
 ---
 ```
 
-Note that as with adaptive text higlighting themes, when you provide a dark and light `highlight-style`, background colors specified in the themes will be ignored in favor of the overall theme specified background colors.
+Note that as with adaptive text higlighting themes, when you provide a dark and light `syntax-highlighting`, background colors specified in the themes will be ignored in favor of the overall theme specified background colors.
 
 {{< include _code-annotation.md >}}
 

diff --git a/docs/output-formats/ms-word.qmd b/docs/output-formats/ms-word.qmd
@@ -14,7 +14,7 @@ format:
   docx:
     toc: true
     number-sections: true
-    highlight-style: github
+    syntax-highlighting: github
 ---
 ```
 

diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd
@@ -2,6 +2,8 @@
 title: PDF Basics
 format: html
 pdf-standard-latex-examples: true
+doc-type:
+  pdf: true
 ---
 
 ## Overview
@@ -60,7 +62,6 @@ See the [Output Options] section below for additional details on customizing LaT
 
 {{< include _document-options-begin.md >}}
 
-
 ## Output Options
 
 There are numerous options available for customizing PDF output, including:

diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd
@@ -4,6 +4,8 @@ tbl-colwidths: [35,65]
 aliases:
   - /docs/prerelease/1.4/typst.html
 pdf-standard-typst-examples: true
+doc-type:
+  typst: true
 # project:
 #   pre-render:
 #     - quarto run ../../tools/snapshot-typst.ts examples/gt-temps.qmd images/typst-tables-gt-temps.png
@@ -121,27 +123,7 @@ Then, any unspecified margins will inherit from the default margins.
 The `columns` option expects a number - the number of columns your body content should have. The default template sets `columns` to `1`. 
 
 
-{{< include /docs/output-formats/_document-options-toc.md >}}
-
-The `toc-indent` option controls how far entries are indented in the displayed table of contents. The default is equivalent to:
-
-```{.yaml}
-toc-indent: 1.5em
-```
-
-{{< include /docs/output-formats/_document-options-section-numbering.md >}}
-
-You can also customize the display of the section numbers with the `section-numbering` YAML option. This option expects a string that describes the numbering schema. For example, the following schema describes numbering sections with numerals, subsection with uppercase letters, and subsubsections with lower case letters, using `.` as a separator:
-
-```yaml
----
-section-numbering: 1.A.a
----
-```
-
-You can read more about specifying the numbering schema in the [Typst documentation for numbering](https://typst.app//docs/reference/model/numbering#parameters-numbering).
-
-{{< include /docs/output-formats/_code-annotation.md >}}
+{{< include /docs/output-formats/_document-options-begin.md >}}
 
 ## Article Layout {#article-layout}
 

diff --git a/docs/presentations/revealjs/index.qmd b/docs/presentations/revealjs/index.qmd
@@ -175,7 +175,15 @@ Custom footer text
 
 ## Code Blocks
 
-Most of the core capabilities of Quarto [HTML Code Blocks](/docs/output-formats/html-code.qmd) are available for Reveal slides, including code folding, code copy, and the ability to pick a custom syntax highlighting theme. Note that if you choose a dark Reveal theme then the default Quarto dark syntax highlighting theme will be used.
+Most of the core capabilities of Quarto [HTML Code Blocks](/docs/output-formats/html-code.qmd) are available for Reveal slides, including code folding, code copy, and the ability to pick a custom syntax highlighting theme.
+
+### Syntax Highlighting
+
+You can specify the code highlighting style using the `syntax-highlighting` option. If you choose a dark Reveal theme then the default Quarto dark syntax highlighting theme will be used. See [HTML Code Blocks: Highlighting](/docs/output-formats/html-code.qmd#highlighting) for the full list of available themes.
+
+::: callout-note
+`syntax-highlighting: idiomatic` is not currently supported for RevealJS presentations. If specified, Quarto falls back to the default Skylighting highlighting with a warning.
+:::
 
 ### Line Highlighting