[mcanouil]

Description

Typst output now supports code annotations and the filename attribute.
# <n> comments become circled numbers on the annotated lines, linked both ways with the list below the block, and a filename shows as a bar above the code block.
Code blocks also get a thin outline (luma(128), which meets the 3:1 of WCAG 1.4.11), so a near-white theme stays visible.
Every code block is drawn through quarto-code-block, which reads its inset, radius and outline from the quarto-code-block-style state, so an extension that frames code blocks itself can drop the outline inside its frame.
Other formats do not have the outline yet, and I will open an issue for it once this pull request is merged.

What needs a careful look:

• format-typst.ts patches Pandoc's generated Skylighting() function and merges the markers that the Lua filter emits.
  A patch that cannot apply warns with the Pandoc version and leaves the block unannotated.
• Extensions that replace Quarto's definitions.typ partial get Quarto's definition of any annotation helper they lack.
  A helper counts as defined only when its definition comes before its first use, so a filter can redefine quarto-code-filename and still call the original, as mcanouil/quarto-code-window#91 does.
  ext-replaces-definitions tests this with a project-local extension, and a document with a filename and annotations also renders with christopherkenny/tufte, a community extension that replaces the partial.
• hover and select use the gutter style, and select warns.

How the pieces fit together is in llm-docs/typst-code-annotations.md.

Known limits:

• Annotated code inside a figure with layout-ncol loses its circles, with a warning that names the cell.
• Per-cell code-annotations options are not read, in any format. This was probably expected, but I was pretty sure it was possible to set it at code cell level.
• With syntax-highlighting: idiomatic or none, code-line-numbers: true shows no line numbers, because Typst's native raw block has none.
• Two annotated executable cells in a row with no list between them lose the first cell, in every format: Annotated code cell is dropped when the next annotated cell comes before any list #15215.
• The helper fallback covers the annotation helpers only. An extension that replaces definitions.typ with an older copy also lacks Quarto's margin and column helpers, so a .column-margin block fails to compile in christopherkenny/tufte with unknown variable: marginalia, on main too. The error is not very useful in Quarto's context, thus why there is a fallback for annotation in this PR. We could imagine to extend and improve this behaviour more generally across partials which would help extensions creators/maintainers.

Before and after

Before is Quarto main, after is this pull request.
Select an image to enlarge it.

Before	After

Case by case:

Case	Before (main)	After (this PR)
filename on a code block	Ignored.	Bar above the block.
Code annotations	Comments removed, "Line N" list.	Circled numbers on the lines, linked both ways with the list.
One annotation over several lines	"Lines 1-2" list.	A circle on each line, one link target.
Annotations in a lst-cap listing	Plain ordered list.	Circles inside the listing.
Ids with . or :	n/a	Supported.
startFrom, with or without code-line-numbers	n/a	Circle follows the code line.
Fenced echo ({{r}})	n/a	Circle on the code line, not the fence.
Annotations with no list after the cell	n/a	Circles still render.
Code inside a layout cell, callout, tabset or figure	n/a	Circles render (see limits for layout-ncol).
syntax-highlighting: idiomatic or none	n/a	Native block, none without a language tag.
Light and dark theme object	n/a	Resolves to the light theme, highlighting kept.
Repeated cell id	n/a	Labels made unique, with a warning.
Annotation items with @fig-x or citations	n/a	Resolved.
Circle text alternative	n/a	"Annotation N".
Code block outline	None.	Thin outline.
Anything that cannot be attached	n/a	Warning with the cell id, no compile error.

Closes #9768.

Checklist

I have (if applicable):

• referenced the GitHub issue this PR closes
• updated the appropriate changelog in the PR
• ensured the present test suite passes
• added new tests
• created a separate documentation PR in Quarto's website repo and linked it to this PR (docs(typst): document code annotations and the filename bar quarto-web#2308)

AI-assisted PR

• AI tool used: Claude Code
• Codebase grounding: local clone, llm-docs
• Human review: I have reviewed, tested, and verified the AI-generated content before submitting.

Note: autonomous AI agents submitting PRs without human oversight are not permitted — see the Code of Conduct.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cderv]

Bad merging conflict resolution it seems... oups. I'll fix this

[cderv]

OK this should fix CI

@mcanouil one thing I notice, the change will add a 'stroke' line across all code blocks

Main

This branch

Is this expected style change for default style (when filename not used) ?

Thanks

[mcanouil]

I need to check, because it's a workaround around skylighting destructing code blocks.

[cderv]

Thanks for this, nice feature. We don't have a lot in v1.10, I was aiming for a improvement and bug fix only. So maybe this should go to v1.11 early as first feature and first pre-release 🤔

Two edge cases found with 🤖 review help (both Skylighting-path only, native path is fine) that end in a hard Typst compile error rather than a graceful fallback. we should probably see if we can cover for them.

[mcanouil]

The stroke was added to ensure the code block could be distinguished from prose regardless of the theme used. For example, github-lighthas a white or near white background which means you no longer see the block and only the code.

One could argue that's fine, especially since that's the behaviour in HTML for example.
edit: I'll push a commit to make it consistent with HTML.

[mcanouil]

Thanks for this, nice feature. We don't have a lot in v1.10, I was aiming for a improvement and bug fix only. So maybe this should go to v1.11 early as first feature and first pre-release 🤔

Two edge cases found with 🤖 review help (both Skylighting-path only, native path is fine) that end in a hard Typst compile error rather than a graceful fallback. we should probably see if we can cover for them.

I can't check the edge cases now, so yes let's put this for 1.11.
I'll use Claude Code to target and find other cases like this to make the feature more robust.

[cderv]

The stroke was added to ensure the code block could be distinguished from prose regardless of the theme used. For example, github-lighthas a white or near white background which means you no longer see the block and only the code.

To be clear, this could be a good idea to add this stroke. Maybe it helps with contrast and accessibility too.

However, if we do that, we probably want to do it in all formats - unless this is a problem with Typst only. I did not check.

[mcanouil]

However, if we do that, we probably want to do it in all formats - unless this is a problem with Typst only. I did not check.

The "missing stroke" is global, so if we want to address this, it should be in a follow-up PR and keep this PR's scope narrow to bringing the missing feature "as is".

The screenshot in #14170 (comment) is from HTML format.

[mcanouil]

The executable-cell bug I noticed while working on this is tracked in #15215.
It happens on main for HTML as well, so I did not make any changes about it here.