docs: update README and example with hotfix config and PR #14170 notice

mcanouil · mcanouil · commit 8e2b6c6848aa · 2026-03-23T22:02:18.000+01:00
Update configuration examples to use nested `hotfix` key. Add hotfix options table and a dedicated "Temporary Hot-fixes (Typst)" section explaining that code-annotations and skylighting fixes will be removed once quarto-dev/quarto-cli#14170 lands. Add callout note in example.qmd about the temporary nature of Typst code-annotations support.
diff --git a/README.md b/README.md
@@ -58,18 +58,30 @@ extensions:
     auto-filename: true
     style: "macos"
     wrapper: "code-window"
-    skylighting-fix: true
+    hotfix:
+      quarto-version: ~
+      code-annotations: true
+      skylighting: true
 ```
 
 ### Options
 
-| Option            | Type    | Default         | Description                                                                         |
-| ----------------- | ------- | --------------- | ----------------------------------------------------------------------------------- |
-| `enabled`         | boolean | `true`          | Enable or disable the code-window filter.                                           |
-| `auto-filename`   | boolean | `true`          | Automatically generate filename labels from the code block language.                |
-| `style`           | string  | `"macos"`       | Window decoration style: `"macos"`, `"windows"`, or `"default"`.                    |
-| `wrapper`         | string  | `"code-window"` | Typst wrapper function name for code-window rendering.                              |
-| `skylighting-fix` | boolean | `true`          | Enable or disable the Skylighting hot-fix for Typst output (block and inline code). |
+| Option          | Type    | Default         | Description                                                          |
+| --------------- | ------- | --------------- | -------------------------------------------------------------------- |
+| `enabled`       | boolean | `true`          | Enable or disable the code-window filter.                            |
+| `auto-filename` | boolean | `true`          | Automatically generate filename labels from the code block language. |
+| `style`         | string  | `"macos"`       | Window decoration style: `"macos"`, `"windows"`, or `"default"`.     |
+| `wrapper`       | string  | `"code-window"` | Typst wrapper function name for code-window rendering.               |
+
+### Hotfix Options
+
+These options are **temporary** and will be removed in a future version (see [Temporary hot-fixes](#temporary-hot-fixes-typst)).
+
+| Option                    | Type    | Default | Description                                                                                |
+| ------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------ |
+| `hotfix.quarto-version`   | string  | _unset_ | Quarto version at or above which all hot-fixes are automatically disabled.                 |
+| `hotfix.code-annotations` | boolean | `true`  | Enable the code-annotations hot-fix for Typst output.                                      |
+| `hotfix.skylighting`      | boolean | `true`  | Enable the Skylighting hot-fix for Typst output (overrides block styling and inline code). |
 
 ### Styles
 
@@ -87,17 +99,32 @@ print("Windows style for this block only")
 ```
 ````
 
-### Typst Skylighting Hot-fix (Integrated)
+### Temporary Hot-fixes (Typst)
+
+The extension includes two temporary hot-fixes for Typst output that compensate for missing Quarto/Pandoc features.
+Both will be removed once [quarto-dev/quarto-cli#14170](https://github.com/quarto-dev/quarto-cli/pull/14170) is released.
+After that, the extension will focus solely on **auto-filename** and **code-window-style** features.
+
+- **`hotfix.code-annotations`**: processes code annotation markers for Typst, since Quarto does not yet support `code-annotations` in Typst output.
+  The `filename` attribute for code blocks will also become natively supported.
+- **`hotfix.skylighting`**: overrides Pandoc's Skylighting output for Typst to fix block and inline code styling.
 
-`code-window` loads its Typst skylighting hot-fix internally from `_extensions/code-window/skylighting-typst-fix.lua`, so no second filter entry is required.
-Set `skylighting-fix: false` to disable the hot-fix without removing the file.
+Set `hotfix.quarto-version` to automatically disable both hot-fixes once you update Quarto to the version that includes native support:
 
-This keeps the hot-fix separated from `code-window.lua` for easy future removal while preserving combined behaviour.
+```yaml
+extensions:
+  code-window:
+    hotfix:
+      quarto-version: "1.10.0"
+```
 
 Future removal playbook:
 
-1. Remove the skylighting loader call in `_extensions/code-window/code-window.lua`.
-2. Delete `_extensions/code-window/skylighting-typst-fix.lua`.
+1. Delete `hotfix` parsing from `code-window.lua` (`HOTFIX_DEFAULTS`, hotfix section in `Meta`).
+2. Remove the `hotfix` section from `_schema.yml`.
+3. Remove the skylighting guard and loader in `main.lua`.
+4. Remove annotation processing from `code-window.lua`.
+5. Delete `_modules/hotfix/` directory entirely.
 
 ## Example
 
diff --git a/example.qmd b/example.qmd
@@ -9,6 +9,7 @@ filters:
   - at: pre-quarto
     path: code-window
 syntax-highlighting: github-dark
+code-annotations: below
 format:
   html:
     output-file: index
@@ -116,6 +117,75 @@ Plain filename on the left, no window decorations.
 print("Default style window")
 ```
 
+## Code Annotations
+
+::: {.callout-note}
+Typst code-annotations support and `filename` attribute handling are temporary hot-fixes.
+They will be removed once Quarto natively supports these features (see [quarto-dev/quarto-cli#14170](https://github.com/quarto-dev/quarto-cli/pull/14170)).
+The extension will then focus on **auto-filename** and **code-window-style** features.
+:::
+
+Code annotations work standalone and together with code-window styling.
+
+### Annotations with Explicit Filename
+
+```{.python filename="annotated.py"}
+import pandas as pd # <1>
+
+df = pd.read_csv("data.csv") # <2>
+summary = df.describe() # <3>
+```
+
+1. Import the pandas library.
+2. Load data from a CSV file.
+3. Generate summary statistics.
+
+### Annotations with Auto-Filename
+
+```python
+def greet(name: str) -> str: # <1>
+    return f"Hello, {name}!" # <2>
+
+result = greet("World") # <3>
+```
+
+1. Define a function with type hints.
+2. Use an f-string for interpolation.
+3. Call the function and store the result.
+
+### Annotations Spanning Multiple Lines
+
+A single annotation number can appear on several consecutive lines.
+Only the first occurrence receives a back-label to avoid duplicates.
+
+```{.python filename="pipeline.py"}
+def process(data): # <1>
+    cleaned = clean(data) # <1>
+    validated = validate(cleaned) # <1>
+    result = transform(validated) # <2>
+    return result # <3>
+```
+
+1. Multi-step input preparation (cleaning and validation).
+2. Apply the main transformation.
+3. Return the final result.
+
+### Annotations without Window Chrome
+
+Set `code-window-enabled="false"` on a block to disable window chrome while keeping annotations.
+
+```{.r code-window-enabled="false"}
+library(ggplot2) # <1>
+ggplot(mtcars) + # <2>
+  aes(x = mpg, y = hp) + # <3>
+  geom_point() # <4>
+```
+
+1. Load the ggplot2 package.
+2. Initialise a plot with the mtcars dataset.
+3. Map aesthetics.
+4. Add a point geometry layer.
+
 ### Configuration
 
 Set the global style in the document front matter:
@@ -124,6 +194,10 @@ Set the global style in the document front matter:
 extensions:
   code-window:
     style: "macos"
+    hotfix:
+      quarto-version: ~
+      code-annotations: true
+      skylighting: true
 ```
 
 Override per block with the `code-window-style` attribute:
