API Reference

deixis-inset-note

Callout whose page defaults to its body declaration; use anchors, offsets or a placement callback for deliberate positioning.

Setup Required

Returns: content.

Task guide

Example

deixis-inset-note(dx: 100pt, dy: 40pt)[Passage][Callout.]

Flow is the factory body layer. Overlay declarations are invisible in flow. The connector layer is independent. Custom containers receive container-args.

deixis-inset-note

deixis-inset-note(..args, mark-type: auto, id: none, data: (:), of: none, numbering: auto, marker: auto, target: auto, series: auto, marker-style: auto, stroke: auto, fill: auto, radius: auto, z-index: auto, marker-position: auto, inline-mode: auto, pins: (), padding: auto, region-shape: auto, inline: false, backlink: auto, connector: auto, width: auto, placement: none, dx: none, dy: none, anchor: (mark: horizon + right, body: horizon + left), anchor-pin: none, layer: auto, render-single: auto, container-func: auto, container-args: (:))

A wrapper for generating inset notes.

This function creates a mark in the text and delegates the body to deixis-inset-note-body.

The city council has voted to pave the trail with
#deixis-inset-note(dx: 10pt, dy: 30pt, width: 100pt)[
  permeable pavement
][
  A porous surface that lets rainwater filter directly into the ground.
].

• ..args (arguments): Accepts up to two positional arguments: [mark][body]. All named arguments are forwarded to deixis-inset-note-body.
• mark-type (auto, str): The type of mark to render in the text. Choices: "inline" | "region" | "phantom".
• id (none, str, label): Names the original annotation created by this wrapper. Without id, its identity is private.
• data (dictionary): Custom annotation fields, kept under note.data. Configure on creation or a standalone body; omit with of.
• numbering (auto, none, str, function, dictionary): The numbering style for the marker.
• marker (auto, content): A hardcoded marker override.
• target (auto, int, label, str): Creation uses the current scope; of inherits the original’s rendering instance. Explicit values override the body scope.
• series (auto, str): Original counter series, defaulting to "default". Omit with of; attachments inherit.
• marker-style (auto, function): A custom styling function for the marker.
• marker-position (auto, alignment, dictionary): Mark marker placement.
• stroke (auto, stroke, none): The border stroke.
• fill (auto, color, none): The background fill color.
• radius (auto, length, dictionary): The border radius.
• inline-mode (auto, str): The visual decoration applied to the marked inline text. Choices: "highlight" | "box" | "parentheses" | "underline" | "text-fill" | "none".
• pins (array): Array of pin names for the region mark.
• padding (auto, length, str, dictionary): Internal padding for the region mark.
• region-shape (auto, function): Shape drawing function for the region mark.
• inline (bool): If true, force the region mark into an inline box.
• backlink (auto, bool, str): Whether to generate a clickable backlink returning the reader to the mark. Choices: bool | "always" | "none" | "never" | "multiple".
• width (auto, length, relative): The width of the inset note body.
• placement (none, function): A custom floating placement function (e.g., Typst’s native #std.place).
• dx (none, length): Absolute horizontal offset for placing the note.
• dy (none, length): Absolute vertical offset for placing the note.
• anchor (dictionary): A dictionary defining how the note aligns to its anchor point (e.g., (mark: horizon + right, body: horizon + left)).
• anchor-pin (none, str, dictionary, array): Pin names or structured targets selecting anchor bounds.
• layer (auto, str, dictionary): Rendering layer for the region mark and/or the body. Choices: "flow" | "foreground" | "background".
• render-single (auto, function): A custom render function for the inner layout of the body.
• container-func (auto, str, function): A custom container wrapper for the body block, or a preset name (“plain”, “rect”, “alert”, “stripe”, “tinted”).

Parameters

..args

Accepts up to two positional arguments: [mark][body]. With of, accepts only [body] and body options. Configure the original mark separately; non-default mark-only options are rejected.

mark-type

The type of mark to render in the text. Choices: "inline" | "region" | "phantom".

id

Names the original annotation created by this wrapper. Without id, its identity is private.

data

Custom annotation fields for creation or a standalone body. Omit with of.

of

Existing original annotation to attach this body to, instead of declaring a new note.

numbering

The numbering style for the marker. A record (restart: "page", pattern: "1") restarts displayed markers per original page; assigned counters stay unchanged. none disables automatic markers and counter allocation.

marker

A hardcoded marker override.

target

Auto uses the current scope for creation and inherits the original’s exact rendering instance with of. Explicit values override the body scope when attached, without moving the original counter.

series

Original counter series, defaulting to "default" for creation. Omit with of; an attachment inherits and cannot redefine the series.

marker-style

A custom styling function for the marker.

stroke

The border stroke.

fill

The background fill color.

radius

The border radius.

z-index

Overlay paint priority; higher integers paint later within a layer. Native flow retains its order. Component dictionaries are supported.

marker-position

Mark marker placement.

See deixis-inline-mark.marker-position and deixis-region-mark.marker-position.

inline-mode

The visual decoration applied to the marked inline text. Choices: "highlight" | "box" | "parentheses" | "underline" | "text-fill" | "none".

See deixis-inline-mark.inline-mode.

pins

Array of pin names for the region mark.

See deixis-region-mark.pins.

padding

Internal padding for the region mark.

See deixis-region-mark.padding.

region-shape

Shape drawing function for the region mark.

See deixis-region-mark.region-shape.

inline

If true, force the region mark into an inline box.

See deixis-region-mark.inline.

backlink

Whether to generate a clickable backlink returning the reader to the mark. Choices: bool | "always" | "none" | "never" | "multiple".

connector

Connector from the original mark to this body. A route name such as "curve" is shorthand for (route: "curve"); a record also sets ports, via/segments, heads, stroke, radius, layer and painters. It merges with deixis-set(connector: ...) defaults field by field; none disables it. Routes also accept settings records such as (kind: "curve", tension: 2).

//| sandbox-mode: "page"
#deixis-inset-note(dx: 4em, dy: 3em, layer: "flow", connector: (route: "right-angle", heads: "stealth"))[Marked][A connected note.]

width

The width of the inset note body.

placement

A custom floating placement function (e.g., Typst’s native #std.place).

See deixis-inset-note-body.placement.

dx

Absolute horizontal offset for placing the note.

See deixis-inset-note-body.dx.

dy

Absolute vertical offset for placing the note.

See deixis-inset-note-body.dy.

anchor

A dictionary defining how the note aligns to its anchor point (e.g., (mark: horizon + right, body: horizon + left)).

See deixis-inset-note-body.anchor.

anchor-pin

A specific #deixis-pin name to anchor the inset note to.

See deixis-inset-note-body.anchor-pin.

layer

Rendering layer for the region mark and/or the body. Choices: "flow" | "foreground" | "background".

See deixis-region-mark.layer and deixis-inset-note-body.layer.

Tip.

Since both deixis-region-mark and deixis-inset-note-body shares this parameter, you can pass layer: (mark: "flow", body: "foreground") to assign different layer to each component.

render-single

A custom render function for the inner layout of the body.

container-func

A body wrapper function or preset name: “plain”, “rect”, “alert”, “stripe” or “tinted”. Forward wrapper options through container-args.

container-args

Native/custom options forwarded only to the body container.

deixis-inset-note-body

deixis-inset-note-body(body, id: none, data: (:), of: none, target: auto, series: auto, marker-style: auto, backlink: auto, stroke: auto, fill: auto, radius: auto, z-index: auto, connector: auto, width: auto, placement: none, dx: none, dy: none, anchor: (mark: horizon + right, body: horizon + left), anchor-pin: none, layer: auto, render-single: auto, container-func: auto, container-args: (:), ..args)

A standalone body content of an inset note.

Body content is preserved. Built-in single renderers fold source indentation with native weak marker spacing and retain explicit paragraph/line breaks.

The body of inset notes are placed at precise geometric coordinates relative an anchor (its mark or a specific pin). They are perfect for callouts.

The artist spent months wandering the dense pine forests, completely captivated by the local #deixis-inline-mark(id: <apricharity>)[apricharity].

#deixis-inset-note-body(
  of: <apricharity>,
  dx: 2.5em,
  dy: 2em,
)[
  warmth of the sun in winter.
]

• body (content): The actual text or content of the note.
• id (none, str, label): Names a standalone body. Use of to attach this body to an original mark.
• data (dictionary): Custom annotation fields, kept under note.data. Configure on creation or a standalone body; omit with of.
• target (auto, int, label, str): Body rendering scope. Auto inherits the original mark’s exact instance, or uses the current scope for standalone bodies.
• series (auto, str): Collection series for a standalone body. Omit with of; attachments inherit the original’s series.
• marker-style (auto, function): A custom styling function for the marker.
• backlink (auto, bool, str): Whether to generate a clickable backlink returning the reader to the mark. Choices: bool | "always" | "none" | "never" | "multiple".
• stroke (auto, stroke, none): The border stroke.
• fill (auto, color, none): The background fill color.
• radius (auto, length, dictionary): The border radius.
• width (auto, length, relative): The width of the inset note body.
• placement (none, function): A custom floating placement function (e.g., Typst’s native place).
• dx (none, length): Absolute horizontal offset for placing the note.
• dy (none, length): Absolute vertical offset for placing the note.
• anchor (dictionary): A dictionary defining how the note aligns to its anchor point (e.g., (mark: horizon + right, body: horizon + left)).
• anchor-pin (none, str, dictionary, array): Pin names or structured targets; selected matches supply bounds and the first selected pin determines the overlay page.
• layer (auto, str): The rendering layer context. Choices: "flow" | "foreground" | "background".
• render-single (auto, function): A custom render function for the inner layout of the body.
• container-func (auto, str, function): A custom container wrapper for the body block, or a preset name (“plain”, “rect”, “alert”, “stripe”, “tinted”).
• ..args (arguments): Additional arguments are rejected; put custom container options in container-args.

Parameters

body

The actual text or content of the note.

id

Names a standalone body. Use of to attach this body to an original mark.

data

Custom annotation fields for creation or a standalone body. Omit with of.

of

Existing original annotation to attach this body to, instead of declaring a new note.

target

Body rendering scope. Auto inherits the original mark’s exact instance, or uses the current scope for a standalone body. An explicit override changes body rendering without moving the original counter.

series

Collection series for a standalone body. Omit with of; attachments inherit their original’s series and reject explicit series arguments.

marker-style

A custom styling function for the marker.

backlink

Whether to generate a clickable backlink returning the reader to the mark. Choices: bool | "always" | "none" | "never" | "multiple".

stroke

The border stroke.

fill

The background fill color.

radius

The border radius.

z-index

Overlay paint priority; higher integers paint later within a layer. Native flow retains its order. Component dictionaries are supported.

connector

Connector from the original mark to this body. A route name such as "curve" is shorthand for (route: "curve"); a record also sets ports, via/segments, heads, stroke, radius, layer and painters. It merges with deixis-set(connector: ...) defaults field by field; none disables it. Routes also accept settings records such as (kind: "curve", tension: 2).

//| sandbox-mode: "page"
#deixis-inset-note(dx: 4em, dy: 3em, layer: "flow", connector: (route: "right-angle", heads: "stealth"))[Marked][A connected note.]

width

The width of the inset note body.

placement

A custom floating placement function (e.g., Typst’s native place).

#let place-func(it) = {
  std.place(top + right, it)
}
#deixis-inset-note(placement: place-func)[Mark][Inset note placed by `placement`.]

dx

Absolute horizontal offset for placing the note.

#deixis-inset-note(dx: 10pt, dy: 10pt)[Mark][Inset note placed with `dx`, `dy`.]

dy

Absolute vertical offset for placing the note.

See deixis-inset-note.dx.

anchor

A dictionary defining how the note aligns to its anchor point (e.g., (mark: horizon + right, body: horizon + left)).

#deixis-inset-note(
  anchor: (mark: bottom + right, body: top + left),
  dx: 0pt, dy: 0pt)[Mark][Inset note anchored to the mark.]

anchor-pin

A specific #deixis-pin name to anchor the inset note to.

#deixis-inset-note(
  anchor-pin: "anchor-pin",
  anchor: (mark: horizon, body: horizon + left),
  layer: auto,
  dx: 0pt, dy: 0pt)[Mark][Inset note anchored to a pin.]

#lorem(3)#deixis-pin("anchor-pin")

See deixis-pin.

Structured targets accept name, scope, select (all/first/last/unique), and page. Flow placement filters to its declaration page before selecting.

layer

The rendering layer context. Choices: "flow" | "foreground" | "background".

Warning.

Similar to deixis-region-mark.layer, the "flow" layer will trigger a #parbreak and disrupt your paragraph. However, it is still recommended to use layer: "flow" whenever possible for stability.

render-single

A custom render function for the inner layout of the body.

container-func

A body wrapper function or preset name: “plain”, “rect”, “alert”, “stripe” or “tinted”. Forward wrapper options through container-args.

container-args

Native/custom options forwarded only to the body container.

..args

Additional arguments are rejected; put custom container options in container-args.