diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index b45fcea03..db0ee34fb 100644 --- a/docs/advanced/environment-vars.qmd +++ b/docs/advanced/environment-vars.qmd @@ -16,8 +16,10 @@ quarto render You can read about other ways to set environment variables in Quarto Projects in [Environment Variables](/docs/projects/environment.qmd). +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable | Description | +| | | +=================================+=============================================================================================================================================================================================================================================================================================================================================================================================================================================================+ +| # Variable | # Description | ++---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_R` | Explicit path to the version of `Rscript` to be used by the `knitr` engine and `quarto run *.R` command. | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_PYTHON` | Explicit path to the version of `python` to be used by the `jupyter` engine and `quarto run *.py` command. | @@ -34,17 +36,17 @@ 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. 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` | 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 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). | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_LOG` | Those variables controls the logging behavior: | | | | -| `QUARTO_LOG_LEVEL` | - `QUARTO_LOG` is the same as using `--log` at command line. It is used to set the path to the log file | +| `QUARTO_LOG_LEVEL` | - `QUARTO_LOG` is the same as using `--log` at command line. It is used to set the path to the log file | | | | -| `QUARTO_LOG_FORMAT` | - `QUARTO_LOG_LEVEL` is the same as using `--log-level` at command line. It is used to set the max level that will be log. Possible values are `DEBUG`, `INFO`(default), `WARNING`, and `ERROR`. | +| `QUARTO_LOG_FORMAT` | - `QUARTO_LOG_LEVEL` is the same as using `--log-level` at command line. It is used to set the max level that will be log. Possible values are `DEBUG`, `INFO`(default), `WARNING`, and `ERROR`. | | | | -| | - `QUARTO_LOG_FORMAT` is the same as using `--log-format` at command line. It is used to set the format for the log. Possible values are `plain` (default) and `json-stream`. | +| | - `QUARTO_LOG_FORMAT` is the same as using `--log-format` at command line. It is used to set the format for the log. Possible values are `plain` (default) and `json-stream`. | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ## Variables Quarto sets @@ -72,22 +74,28 @@ ENV["QUARTO_DOCUMENT_PATH"] ``` ::: -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable | Description | -+============================================+=================================================================================================================================================================================================+ -| `QUARTO_PROJECT_ROOT` | Root of the project, or the directory of the file if not in project mode | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_DOCUMENT_PATH` | Directory of the document being rendered | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_DOCUMENT_FILE` | Name of the file being rendered | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_PROFILE` | Profile used, e.g `QUARTO_PROFILE=advanced,production` for `quarto render --profile advanced,production` | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with [execution information for Quarto engines](./quarto-execute-info.qmd). This is accessible by code in executable code cells. | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | | ++============================================+==========================================================================================================================================================================================================+ +| # Variable | # Description | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_PROJECT_ROOT` | Root of the project, or the directory of the file if not in project mode | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_DOCUMENT_PATH` | Directory of the document being rendered | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_DOCUMENT_FILE` | Name of the file being rendered | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_PROFILE` | Profile used, e.g `QUARTO_PROFILE=advanced,production` for `quarto render --profile advanced,production` | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with [execution information for Quarto engines](./quarto-execute-info.qmd). This is accessible by code in executable code cells. | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_PROJECT_SCRIPT_PROGRESS` | Set to `"1"` when progress output can be shown during [pre/post render scripts](/docs/projects/scripts.qmd) (e.g. rendering multiple files), `"0"` otherwise. \| | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_PROJECT_SCRIPT_QUIET` | Set to `"1"` when the `--quiet` flag is active during [pre/post render scripts](/docs/projects/scripts.qmd), `"0"` otherwise. \| | ++--------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd). \ No newline at end of file diff --git a/docs/projects/scripts.qmd b/docs/projects/scripts.qmd index 3677ee1fc..c88300fe4 100644 --- a/docs/projects/scripts.qmd +++ b/docs/projects/scripts.qmd @@ -60,6 +60,10 @@ The following environment variables are passed to pre and post-render scripts (n | `QUARTO_PROJECT_OUTPUT_DIR` | Output directory | | `QUARTO_PROJECT_INPUT_FILES` | Newline separated list of all input files being rendered (passed only to `pre-render`) | | `QUARTO_PROJECT_OUTPUT_FILES` | Newline separated list of all output files rendered (passed only to `post-render`). | +| `QUARTO_PROJECT_SCRIPT_PROGRESS` | Set to `"1"` when progress output can be shown (e.g. rendering multiple files), `"0"` otherwise. | +| `QUARTO_PROJECT_SCRIPT_QUIET` | Set to `"1"` when the `--quiet` flag is active, `"0"` otherwise. | + +Scripts can use `QUARTO_PROJECT_SCRIPT_PROGRESS` and `QUARTO_PROJECT_SCRIPT_QUIET` to adapt their output, for example by suppressing progress indicators when running in quiet mode or when progress display is not available. The project metadata and render list will be re-computed after any pre-render scripts have executed, allowing them to modify this project data. For example, a pre-render script might generate additional `qmd` files or `ipynb` files that should be rendered.