feat(typst): add code annotation and filename support by mcanouil · Pull Request #14170 · quarto-dev/quarto-cli

mcanouil · 2026-03-06T20:15:42Z

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.
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.
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 · 2026-03-06T20:16:03Z

✅ 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.

Add cell-id generation and Typst label/link support so that clicking a circled annotation number in code jumps to its description and vice versa. Add upstream-compatible Quarto functions (quarto-circled-number, quarto-annote-color, quarto-code-filename, quarto-code-annotation, quarto-annotation-item) to definitions.typ for forward compatibility with quarto-dev/quarto-cli#14170.

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.

cderv · 2026-07-22T16:20:20Z

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

cderv · 2026-07-23T09:15:28Z

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 · 2026-07-23T09:22:34Z

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 · 2026-07-23T09:40:15Z

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 · 2026-07-23T09:45:43Z

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 · 2026-07-23T10:00:47Z

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 · 2026-07-23T10:14:13Z

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.

…ace definitions.typ

…otated rows

…n notes

… startFrom

mcanouil · 2026-10-27T17:01:46Z

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.

mcanouil self-assigned this Mar 6, 2026

mcanouil changed the title ~~feat(typst)= Add code annotation and filename support~~ feat(typst): add code annotation and filename support Mar 6, 2026

mcanouil marked this pull request as ready for review March 9, 2026 09:56

mcanouil mentioned this pull request Mar 23, 2026

feat: add bidirectional linking to Typst code annotations mcanouil/quarto-mcanouil#100

Merged

mcanouil mentioned this pull request Mar 23, 2026

refactor: consolidate hotfix options under nested key mcanouil/quarto-code-window#7

Merged

This comment was marked as outdated.

Sign in to view

cderv assigned cderv and unassigned mcanouil Jul 22, 2026

cderv self-requested a review July 22, 2026 15:52

mcanouil commented Jul 23, 2026

View reviewed changes

Comment thread src/resources/formats/typst/pandoc/quarto/definitions.typ Outdated

mcanouil commented Jul 23, 2026

View reviewed changes

Comment thread src/format/typst/format-typst.ts Outdated

cderv reviewed Jul 23, 2026

View reviewed changes

Comment thread src/format/typst/format-typst.ts Outdated

Comment thread src/resources/filters/modules/typst-code-annotations.lua Outdated

cderv added the early-in-release An issue that should be worked on early in the release (likely due to risk) label Jul 23, 2026

cderv added this to the v1.11 milestone Jul 23, 2026

mcanouil marked this pull request as draft July 27, 2026 18:09

mcanouil marked this pull request as ready for review July 27, 2026 19:20

mcanouil mentioned this pull request Sep 18, 2026

DecoratedCodeBlock has no docx/pptx renderer — code chunk filename header silently dropped #14906

Open

mcanouil marked this pull request as draft October 19, 2026 11:53

mcanouil force-pushed the feat/typst-annotation-filename branch from a63e76e to 8092d5e Compare October 27, 2026 10:19

mcanouil added 24 commits October 27, 2026 16:47

test: cover annotation edge cases in Typst output

cb7a2ce

fix: keep Typst annotation labels unique for repeated cell ids

e79f3e2

docs: list the figure div limit for Typst code annotations

ff02107

test: document figure divs as a known limit of Typst annotations

a7c72cc

docs: merge the duplicate figure div limit

3645540

fix: keep annotated Typst code blocks inside figure floats

63764d3

fix: keep Typst annotation cell ids unique across containers

4a04914

docs: mention the Typst code block outline in the changelog

96147ff

fix: use a 3:1 contrast outline for Typst code blocks

a5aa93c

fix: stop the annotation circle from adding row height in Typst

b4ee05f

fix: centre the Typst annotation circles on their text lines

fe00834

fix: define missing annotation helpers for Typst extensions that repl…

a2a0589

…ace definitions.typ

test: add the partials of the extension that replaces definitions.typ

61ba0e1

fix: remove the extra height the annotation circle added to later ann…

9d9c05b

…otated rows

docs: explain the zero-height box of the annotation circle

9e6e8fd

chore: remove build output that was committed by mistake

b9771d0

fix: break long Typst filenames at separators first

1a41a4c

fix: centre the annotation circles on the cap height of their text

01b76fc

fix: keep the extension of long Typst filenames attached

241c41f

fix: avoid a backslash-dot sequence in the Typst filename helper

b2b9fea

docs: correct the filename breaking thresholds in the Typst annotatio…

2685540

…n notes

fix: inject the Typst annotation helpers at the top level of the file

543a134

fix: warn about duplicate cell ids only for annotated Typst blocks

3f6374e

fix: shift annotated lines past the fence of a fenced echo block with…

e1f8b9b

… startFrom

mcanouil mentioned this pull request Oct 27, 2026

Annotated code cell is dropped when the next annotated cell comes before any list #15215

Open

mcanouil force-pushed the feat/typst-annotation-filename branch from f5f8457 to e1f8b9b Compare October 27, 2026 17:02

Merge branch 'main' into feat/typst-annotation-filename

2bd9f23

mcanouil marked this pull request as ready for review October 28, 2026 09:25

mcanouil requested a review from cderv October 28, 2026 09:47

Conversation

mcanouil commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

posit-snyk-bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

cderv commented Jul 22, 2026

Uh oh!

cderv commented Jul 23, 2026

Uh oh!

Uh oh!

mcanouil commented Jul 23, 2026

Uh oh!

Uh oh!

cderv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mcanouil commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcanouil commented Jul 23, 2026

Uh oh!

cderv commented Jul 23, 2026

Uh oh!

mcanouil commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcanouil commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mcanouil commented Mar 6, 2026 •

edited

Loading

posit-snyk-bot commented Mar 6, 2026 •

edited

Loading

mcanouil commented Jul 23, 2026 •

edited

Loading

mcanouil commented Jul 23, 2026 •

edited

Loading

mcanouil commented Oct 27, 2026 •

edited

Loading