codly.new

Creates a formatted code block. codly.new is an alias of codly.codly; codly.set_, codly.show_, and codly.selector target the same element.

Signature

codly.new(body, ..fields)

body is positional and required. It accepts source text, a path, or content containing raw blocks. Other fields are named. The setters accept named field values; show_ installs a scoped replacement callback, and selector creates a Typst selector for block instances.

Fields

Behavior

Fields are validated and cast by their declared types. Gutter arrays and functions cast to gutter-column; gutters: auto includes the ordinary number column when enabled, and custom columns remain when number-enabled is false. Custom gutters replace diff’s automatic old/new/marker columns. Diff colors may be paints, none, auto (the ordinary row fill), or callbacks receiving a row with diff information. Explicit highlights take precedence over diff backgrounds.

Ranges select source lines before display. Diff references count displayed patch rows; highlight and callout character positions count code characters without diff markers. Diff context uses new-side syntax, and each hunk or file is highlighted independently.

#show: codly.set_(..fields) sets named field defaults in scope. #show: codly.show_(it => content) replaces matching blocks with the callback result; return it inside the result to retain the block. #show codly.selector(): it => content uses a native Typst selector. selector accepts outline, outer, and meta boolean options, all defaulting to false; these select Elembic representation layers rather than filtering fields.

Example

Try the controls

Language

"python"

PythonRust

Adjust a value to update the source and preview. Changes stay in this tab.

Reset controls

</> Typst source

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

#set raw(lang: example-language)

#codly.new(
  ```
  def greet(name):
      print(f'Hello, {name}!')
  ```,
  file: "greeting.py",
  offset: 10,
)

Edit & run on your device

Editable Typst source#import "@preview/codly:2.0.0" as codly #set raw(lang: example-language) #codly.new( ``` def greet(name): print(f'Hello, {name}!') ```, file: "greeting.py", offset: 10, )

The controls supply the example variables. Their definitions are hidden here; Copy code includes the current values and your edits.

Run Reset example

OUTPUTPre-rendered default

Example: Automatic Code Blocks

</> Typst source

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

#show raw.where(block: true): codly.new

```py
def greet(name):
    print(f'Hello, {name}!')
```

Edit & run on your device

Editable Typst source#import "@preview/codly:2.0.0" as codly #show raw.where(block: true): codly.new ```py def greet(name): print(f'Hello, {name}!') ```

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

Run Reset example

OUTPUTPre-rendered default

Example: Listing Figures

Wrap a block in a native figure to give it a caption and listing number. Codly’s raw, string, and path inputs infer kind: raw, so the same selector styles captions and builds a listings outline.

</> Typst source

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

#show figure.where(kind: raw): set figure.caption(position: top)

#figure(
  codly.new(
    ```py
    def load_config(path):
        with open(path) as source:
            return source.read()
    ```,
  ),
  caption: [Read the configuration file.],
)<load-config>

@load-config opens the file on @load-config:2.

#outline(target: figure.where(kind: raw), title: [Listings])

OUTPUT

Example: Scoped Styling

Use a content block to apply a style to a group of examples. The block setter changes shared block defaults; the line setter changes row appearance. After the closing ], subsequent code blocks use the outer defaults again.

</> Typst source

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

#[
  #show: codly.set_(radius: 8pt)
  #show: codly.line-set_(
    fill: rgb("#eef5ff"),
    stroke: 0.6pt + rgb("#bdd5ef"),
  )

  #codly.new(
    ```py
    timeout = 30
    retries = 3
    ```,
    file: "settings.py",
  )
]

#codly.new(
  ```py
  connect(timeout=timeout)
  ```,
  file: "client.py",
)

OUTPUT

Example: Source Excerpts

Select an inclusive range of source lines without rewriting the code. This example displays source lines 2 through 4, with a filename badge and numbering starting at 1.

</> Typst source

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

#let source = ```py
import json
def read_settings(path):
    with open(path) as file:
        return json.load(file)
print(read_settings('settings.json'))
```

#codly.new(
  source,
  file: "settings.py",
  range: (2, 4),
  offset: auto,
)

Edit & run on your device

Editable Typst source#import "@preview/codly:2.0.0" as codly #let source = ```py import json def read_settings(path): with open(path) as file: return json.load(file) print(read_settings('settings.json')) ``` #codly.new( source, file: "settings.py", range: (2, 4), offset: auto, )

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

Run Reset example

OUTPUTPre-rendered default