Codly Typst Package

Codly allows you to create cross-references to your code elements using Typst labels:

• Lines: Use the shorthand @<label>:<line>.
• Highlights/Annotations: Use the label shorthand @<highlight>.

To use Codly, you must initialize it once per document using a show rule. You can then optionally configure it using the #codly() function.

Note that configuration changes are global unless you use the codly.local function. Any parameter left blank will retain its previous value or use the default, similar to a Typst set rule.

#import "@preview/codly:1.3.1": *
#import "@preview/codly-languages:0.1.1": *
#show: codly-init.with()

// Optional configuration
#codly(
  languages: codly-languages
)

If you want to prevent Codly from styling specific code blocks, you can use either #codly-disable() or the #no-codly[] content wrapper.

• #codly-disable(): Disables Codly from the current point forward until re-enabled via #codly().
• #no-codly[ ... ]: Wraps specific content to be displayed as standard Typst raw blocks.

// Method 1: Disable from this point onwards
#codly-disable()

// Method 2: Wrap specific content
#no-codly[
  ```typ
  I will be displayed using the normal raw blocks.

]

By default, Codly uses smart-indent, which detects the indentation of your code block and adjusts the horizontal offset for line wrapping. You can disable this behavior using the smart-indent parameter in the #codly() function.

#codly(smart-indent: false)

You can add a vertical offset to a code block without selecting a specific subset of lines using #codly-offset(n).

// Sets a 5 line offset
#codly-offset(5)

You can insert a visual 'skip' (represented by …) between lines using the skips parameter in #codly(). The skips parameter accepts an array of tuples in the format (line_index, jump_size).

Note: Line indexing starts at 0.

// Before the 5th line (index 4), insert a 32 line jump.
#codly(skips: ((4, 32), ))

Use #codly-range(start: n, end: m) to select a specific range of lines within a code block. To select from a specific line to the very end of the block, set end: none.

#codly-range(start: 5, end: 10)

Use the annotations parameter in #codly() to add descriptive content to a range of lines.

Each annotation is a dictionary containing:

• start: The starting line index (0-indexed).
• end: The ending line index.
• content: The Typst content to display as the annotation.

#codly(
  annotations: (
    (
      start: 2,
      end: 4,
      content: block(width: 2em, [Function body])
    ),
  )
)

To align an offset with a 'parent' code block, use the offset-from argument in the #codly() function and provide the Typst label of the parent block.

#codly(offset-from: <parent>)

Use the highlights parameter in #codly() to apply background colors to specific lines or segments of lines.

Each highlight is a dictionary containing:

• line: The line index.
• start: The character start position.
• end: The character end position (none for end of line).
• fill: The color to use.
• tag: (Optional) A label/tag to display (e.g., "(a)").

#codly(highlights: (
  (line: 4, start: 2, end: none, fill: red),
  (line: 5, start: 13, end: 19, fill: green, tag: "(a)"),
  (line: 5, start: 26, fill: blue, tag: "(b)"),
))

You can customize several visual aspects of the code block via the #codly() function:

• Disable line numbers: Set number-format: none.
• Disable zebra striping: Set zebra-fill: none or zebra-fill: white.
• Customize border: Set stroke: <color/thickness> (e.g., 1pt + red).
• Disable language icon: Set display-icon: false.

#codly(
  number-format: none,
  zebra-fill: none,
  stroke: 1pt + red,
  display-icon: false
)