docs: Document chrome-headless-shell as primary browser install

Update diagrams.qmd Chrome Install section to recommend
chrome-headless-shell over legacy chromium. Update QUARTO_CHROMIUM
env var description with browser discovery priority order.

CLI reference docs will be regenerated from next prerelease build.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cderv

docs/advanced/environment-vars.qmd

@@ -34,7 +34,7 @@ You can read about other ways to set environment variables in Quarto Projects in
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `QUARTO_TEXLIVE_BINPATH`        | Explicit path to the TeX Live binaries to be passed to `tlmgr option sys_bin` used when setting `tlmgr` and related to `PATH` using `tlmgr add path` . By default, Quarto looks in known places.                                                                                                                                                                                                                                                            |
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `QUARTO_CHROMIUM`               | Explicit path to binary to use for chrome headless. Quarto uses [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) to do screenshot of HTML diagrams for PDF insertion. The binary must be compatible with this protocol. (e.g. Chrome, Chromium, Chrome Headless Shell, Edge, ...)                                                                                                                                            |
+| `QUARTO_CHROMIUM`               | Explicit path to binary to use for chrome headless. When not set, Quarto searches for browsers in this order: (1) Quarto-installed Chrome Headless Shell, (2) system Chrome or Edge, (3) legacy Puppeteer Chromium. The binary must be compatible with [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) (e.g. Chrome, Chromium, Chrome Headless Shell, Edge, ...).                                                                                                                                            |
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `QUARTO_CHROMIUM_HEADLESS_MODE` | Used for adaption of the `--headless` mode used with `QUARTO_CHROMIUM` binary. Set to `"none"` for `--headless` , or to `"old"` or `"new"` to pass as argument, e.g. `--headless=<QUARTO_CHROMIUM_HEADLESS_MODE>` . Quarto 1.6 sets `"old"` as default, which works from Chrome 112 to 131. Starting Quarto 1.7.13, `"none"` is the default as [Chrome 132 removed old headless mode](https://developer.chrome.com/blog/removing-headless-old-from-chrome). |
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

docs/authoring/diagrams.qmd

@@ -23,7 +23,7 @@ As illustrated above, Mermaid diagrams are embedded using `{mermaid}` executable
 
 
 ::: callout-note
-For print output formats like `pdf` or `docx`, diagram rendering makes use of the Chrome or Edge web browser to create a high-quality PNG. Quarto can automatically use an existing version of Chrome or Edge on your system, or alternatively if you don't have either installed, can use a lighter-weight library version of Chrome (see [Chrome Install](#chrome-install) below for details).
+For print output formats like `pdf` or `docx`, diagram rendering makes use of the Chrome or Edge web browser to create a high-quality PNG. Quarto can automatically use an existing version of Chrome or Edge on your system, or alternatively if you don't have either installed, you can install a lighter-weight version called Chrome Headless Shell (see [Chrome Install](#chrome-install) below for details).
 :::
 
 ## Mermaid
@@ -236,12 +236,16 @@ To include code for `{dot}`, add `//| echo: true` to the top of the cell. For ex
 
 For printing to output formats like `pdf` or `docx`, diagram rendering makes use of the Chrome or Edge web browser to create a high-quality PNG.
 
-Quarto can automatically use an existing version of Chrome or Edge on your system for rendering. Alternatively, if you don't have either, you can install a minimal version of Chrome for use by Quarto with the following command:
+Quarto can automatically use an existing version of Chrome or Edge on your system for rendering. Alternatively, if you don't have either installed, you can install Chrome Headless Shell for use by Quarto:
 
 ``` {.bash filename="Terminal"}
-quarto install chromium
+quarto install chrome-headless-shell
 ```
 
+[Chrome Headless Shell](https://developer.chrome.com/blog/chrome-headless-shell) is a lightweight, headless-only browser from Google's [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) infrastructure. It has fewer system dependencies than full Chromium, making it a good fit for Docker containers and WSL environments.
+
 ::: callout-note
-Quarto installs headless Chromium via Puppeteer. The bundled Chromium that Puppeteer installs may not work on Docker containers; please check [the Puppeteer documentation](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker) as well as [this article](https://pptr.dev/next/troubleshooting#running-puppeteer-on-wsl-windows-subsystem-for-linux) if you are attempting to install within Windows Subsystem for Linux (WSL).
+## Legacy Chromium
+
+The older `quarto install chromium` command (which installs Chromium via Puppeteer) is still available but no longer recommended. If you use it, note that the Puppeteer-bundled Chromium may not work in Docker or WSL — see [Puppeteer troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker) for details.
 :::