example.qmd

---
title: "Code Window"
subtitle: "Quarto Extension"
author:
  - name: "Mickaël CANOUIL, _Ph.D._"
    orcid: "0000-0002-3396-4549"
    url: "https://mickael.canouil.fr"
filters:
  - at: pre-quarto
    path: code-window
syntax-highlighting: github-dark
code-annotations: below
toc: true
format:
  html:
    output-file: index
    embed-resources: true
  typst:
    output-file: example-typst
    papersize: a4
    keep-typ: true
    margin:
      x: 2.5cm
      y: 2.5cm
  revealjs:
    output-file: example-revealjs
    embed-resources: true
format-links:
  - html
  - typst
  - revealjs
---

{{< pagebreak >}}

## Explicit Filename

Code blocks with a `filename` attribute display a window header with the filename.
The decoration style depends on the `style` option (default: `"macos"`).

```{.python filename="fibonacci.py"}
def fibonacci(n: int) -> int:
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
```

```{.r filename="analysis.R"}
# Load data and create summary
data <- read.csv("data.csv")
summary(data)
```

{{< pagebreak >}}

## Auto-Generated Filename

With `auto-filename: true` (the default), code blocks without explicit filenames automatically show the language name in small-caps styling.

```python
def greet(name: str) -> str:
    """Return a greeting message."""
    return f"Hello, {name}!"
```

```r
# Create sample data
data <- data.frame(
  x = 1:10,
  y = rnorm(10)
)
summary(data)
```

```bash
#!/bin/bash
echo "Hello, World!"
```

{{< pagebreak >}}

## Plain Code Block

Code blocks without a language are not affected by the extension.

```
This is a plain code block without any language specified.
No window decoration is applied here.
```

{{< pagebreak >}}

## Disabled Auto-Filename

### Per Block

Set `code-window-no-auto-filename="true"` on a single block to suppress the auto-generated filename without changing the global setting.

```{.python code-window-no-auto-filename="true"}
print("No auto-filename on this block")
```

### Globally

To disable auto-generated filenames for the entire document, set `auto-filename: false` in the extension configuration.
Only code blocks with an explicit `filename` attribute will display window decorations.

```yaml
extensions:
  code-window:
    auto-filename: false
```

{{< pagebreak >}}

## Window Styles

Three decoration styles are available via the `style` option.
The global style can be set in the document configuration.
Individual blocks can override the style with the `code-window-style` attribute.

### macOS Style (default)

Traffic light buttons on the left, filename on the right.

```{.python filename="macos-example.py" code-window-style="macos"}
print("macOS style window")
```

### Windows Style

Minimise, maximise, and close buttons on the right, filename on the left.

```{.python filename="windows-example.py" code-window-style="windows"}
print("Windows style window")
```

### Default Style

Plain filename on the left, no window decorations.

```{.python filename="default-example.py" code-window-style="default"}
print("Default style window")
```

{{< pagebreak >}}

## 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:

```yaml
extensions:
  code-window:
    enabled: true
    auto-filename: true
    style: "macos"
    wrapper: "code-window"
    hotfix:
      code-annotations: true
      skylighting: true
      typst-title: true
```

Each hotfix accepts either a boolean or a map with `enabled` and `quarto-version` keys for per-hotfix version thresholds:

```yaml
extensions:
  code-window:
    hotfix:
      code-annotations: true
      skylighting:
        enabled: false
      typst-title:
        quarto-version: "1.10.0"
```

Override per block with the `code-window-style` attribute:

````markdown
```{.python filename="example.py" code-window-style="windows"}
print("Windows style for this block only")
```
````