From 2f78f1d26c894df69a73e0306c0ca3bff3746492 Mon Sep 17 00:00:00 2001
From: matthew p robertson <35159349+mpr1255@users.noreply.github.com>
Date: Wed, 23 Oct 2024 18:54:57 +1100
Subject: [PATCH] Update typst.qmd

Add explainer of the hidden QUARTO_TYPST env variable feature...
---
 docs/output-formats/typst.qmd | 36 +++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd
index 65489278d..1157050d6 100644
--- a/docs/output-formats/typst.qmd
+++ b/docs/output-formats/typst.qmd
@@ -315,3 +315,39 @@ format:
       - text: |
           #show heading: set text(navy)
 ```
+## Custom Typst Configuration
+
+By default, Quarto uses its built-in version of Typst to ensure compatibility and stable behavior. However, for advanced users who need to use features from newer Typst versions, Quarto can be configured to use an external Typst installation through the `QUARTO_TYPST` environment variable.
+
+For example:
+
+```bash
+# Unix/macOS
+export QUARTO_TYPST=/path/to/typst
+
+# Windows PowerShell
+$env:QUARTO_TYPST = "C:\path\to\typst"
+```
+
+:::caution
+Using a custom Typst installation is considered experimental and may lead to unexpected behavior. Quarto makes no guarantees about compatibility when using versions of Typst other than the built-in version. Use this configuration at your own risk.
+:::
+
+The custom Typst binary can be installed through various package managers, including homebrew, cargo, Nix, and more.
+
+```bash
+# Homebrew (macOS/Linux)
+brew install typst
+
+# Cargo (Cross-platform)
+cargo install typst
+
+# Nix (Cross-platform)
+nix-env -iA nixpkgs.typst
+```
+
+After setting `QUARTO_TYPST` and refreshing your shell, verify the configuration by checking which version of Typst Quarto is using:
+
+```bash
+quarto typst --version
+```