docs(typst): document code annotations and the filename bar

docs/authoring/code-annotation.qmd

@@ -32,13 +32,22 @@ The default HTML annotation style displays annotations in a list below the code
 format: revealjs
 ```
 
-The PDF format also allows for annotations, numbering, and displaying the annotation text below the code. In other formats, like Word and GitHub Markdown, annotations are instead labeled with the line of code (or lines of code) to which the annotation text applies.
+The PDF and Typst formats also allow for annotations, numbering, and displaying the annotation text below the code. In other formats, like Word and GitHub Markdown, annotations are instead labeled with the line of code (or lines of code) to which the annotation text applies.
 
 ::: panel-tabset
 #### PDF
 
 ![](images/annote-pdf.png){fig-alt="Screenshot of output in PDF format showing code annotation."}
 
+#### Typst
+
+{{< prerelease-callout 1.12 >}}
+
+In Typst output, each annotation number is a circle at the end of the annotated line, and links to the annotation text below the code block.
+The annotation text links back to the line.
+
+![](images/annote-typst.png){fig-alt="Screenshot of output in Typst format showing code annotation: circled numbers 1 and 2 at the end of the annotated lines of an R code block, and the two annotation texts below it."}
+
 #### GitHub Flavored Markdown
 
 ````markdown
@@ -64,6 +73,7 @@ add new columns for the bill ratio and bill area.
 To add code annotation to a code block, you need to add two things: specially formatted code comments in your code cell, and an ordered list below the code cell with the annotation text. Read more in [Annotation Syntax](#annotation-syntax).
 
 The `code-annotations` option controls how annotations appear in the HTML format (`below` (default), `hover` or `select`), and in all formats, whether annotation is disabled (`false`), or if annotations should be removed from the output (`none`).
+In Typst output, the `hover` and `select` styles use the same layout as `below`.
 
 ## Annotation Syntax {#annotation-syntax}
 

docs/authoring/markdown-basics.qmd

@@ -404,6 +404,8 @@ code
 ```
 ````
 
+In HTML and Typst output, the filename shows as a bar above the code block.
+
 If you are creating HTML output there is a wide variety of options available for code block output. See the article on [HTML Code](/docs/output-formats/html-code.qmd) for additional details.
 
 ## Raw Content

docs/output-formats/html-code.qmd

@@ -227,7 +227,7 @@ plt.plot([1,23,2,4])
 plt.show()
 ```
 
-Non-HTML formats will still have the filename, but it will simply be shown in bold above the code block.
+Typst output shows the filename in a bar above the code block. Other non-HTML formats will still have the filename, but it will simply be shown in bold above the code block.
 
 ## Highlighting
 

docs/output-formats/typst-custom.qmd

@@ -96,6 +96,40 @@ Use the [source code](https://github.com/quarto-dev/quarto-cli/blob/main/src/res
 
 The [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) format provides an example of redefining the main template (in that case, it is to prevent automatic bibliography processing by Quarto in deference to the built-in handling of the Typst AMS template).
 
+### Code Blocks
+
+{{< prerelease-callout 1.12 >}}
+
+Two Typst definitions control how Quarto draws code blocks.
+A custom format can change them in its `typst-template.typ` partial, which comes after Quarto's definitions.
+A filter can change them with a raw `typst` block.
+
+`quarto-code-filename(filename, body)` draws each code block that has a `filename`.
+The default shows the filename in a bar above the code.
+To draw a different frame, define a new `quarto-code-filename` with the same arguments.
+To keep the default for some blocks, save it under another name before the new definition, for example `#let native-code-filename = quarto-code-filename`.
+
+`quarto-code-block-style` is a Typst state that holds the `inset`, `radius` and `stroke` of each code block.
+To change the code blocks in one part of the document, update the state before that part and restore it after.
+
+The example below draws a frame around each code block that has a `filename`.
+Inside the frame, the code block has no radius and no outline of its own, so the frame is the only border:
+
+``` {.typst filename="typst-template.typ"}
+#let quarto-code-filename(filename, body) = context {
+  let outer = quarto-code-block-style.get()
+  block(width: 100%, stroke: 1pt + luma(160), radius: 6pt, clip: true)[
+    #set block(spacing: 0pt)
+    #block(width: 100%, fill: luma(235), inset: 6pt)[#filename]
+    #quarto-code-block-style.update((..outer, radius: 0pt, stroke: none))
+    #body
+    #quarto-code-block-style.update(outer)
+  ]
+}
+```
+
+If a format replaces the `definitions.typ` partial and does not define these helpers, Quarto adds them before the first line that uses them.
+
 ## Bundling Typst Packages
 
 If your custom format uses packages from the Typst preview namespace (e.g., `@preview/cetz`), you can bundle them with your extension for offline use. The `quarto call typst-gather` command scans your template files for `@preview` imports and downloads the packages.