`codly.annotation-ref`

A native reference element created for a labelled annotation in a code block inside a figure.

Signature

// Create a new annotation reference.
codly.annotation-ref(body, block: label, line: int, item: content, by: "line" | "item", suffix: none, separator: auto, numbering: auto)

// Equivalent set-rule for an annotation reference.
codly.annotation-ref-set_(..args)

// Override the show-rule for an annotation reference.
codly.annotation-ref-show_(it, ..args)

Codly creates this element when Typst resolves a native reference such as @note. Use annotation-ref-set_(...) to set fields in scope, or annotation-ref-show_(callback) to replace or transform its display.

Fields

Field	Type	Default / required	Meaning
`body`	`none \| content`	Required, positional	Internal reference body.
`block`	`label`	Required, named	Label of the containing code block or figure.
`line`	`int`	Required, named	Displayed number of the first line covered by the annotation.
`item`	`content`	Required, named	Annotation content or automatic annotation number displayed when by is "item".
`suffix`	`none \| content`	`none`	Suffix identifying an unnumbered start line.
`by`	`"line" \| "item"`	Required, named	Whether the reference displays the line number or annotation item.
`separator`	`none \| auto \| str \| content`	`auto`	Separator after the block reference; auto inherits codly.ref.sep.
`numbering`	`none \| auto \| function`	`auto`	Line-number formatter; auto inherits codly.ref.numbering, and none hides the line number.

by, separator, and numbering can also be set for all generated references with codly.ref. Explicit fields on this element take precedence. In item mode, the annotation’s content is used; numbering and suffix apply only to line mode. With line mode and numbering: none, the rendered reference contains just the native reference to the code block.

annotation-ref-show_ receives the generated reference element, so a callback can inspect or wrap it. For example, #show: codly.annotation-ref-show_(it => [Note: #it]) prefixes each displayed annotation reference while keeping its existing rendering.

Example: Basic usage

With the default line mode, the reference appends the displayed line number to the figure reference:

#import "@preview/codly:2.0.0" as codly

#figure(caption: [A code example])[
  #codly.new(
    ```
    first line
    second line
    ```,
    annotations: ((start: 2, label: <note>, content: [the note]),),
  )
]<example>

The annotation reference is @note.

Edit & run on your device

Editable Typst source

The highlighted source and output update after you stop typing. Copy code includes your edits.

Example: Item-based reference

With by: "item", the suffix is the annotation’s content; the show rule adds a prefix:

#import "@preview/codly:2.0.0" as codly

#show: codly.ref-set_(by: "item", sep: " — ")
#show: codly.annotation-ref-show_(it => [Note: #it])

#figure(caption: [A code example])[
  #codly.new(
    ```
    first line
    second line
    ```,
    annotations: ((start: 2, label: <note>, content: [the note]),),
  )
]<example>

The annotation reference is @note.

Edit & run on your device

Editable Typst source

The highlighted source and output update after you stop typing. Copy code includes your edits.