API Reference

deixis-sidenote

Margin-note presets for the outside margin and loose mark alignment.

Setup Required

Returns: content.

Task guide

Example

deixis-sidenote[A brief aside.]

Uses margin-note configuration/query type. Explicit arguments override the preset; mark-align-strictness: auto resumes configured strictness.

deixis-sidenote

deixis-sidenote(..args, mark-type: auto, id: none, data: (:), of: none, numbering: auto, marker: auto, target: auto, series: auto, marker-style: auto, marker-position: auto, stroke: auto, fill: auto, radius: auto, z-index: auto, inline-mode: auto, pins: (), padding: auto, region-shape: auto, layer: auto, inline: false, backlink: auto, connector: auto, width: 90%, dx: auto, dy: 0pt, side: "outside", side-strategy: auto, mark-align: auto, mark-align-strictness: "loose", spillover: auto, overflow: auto, anchor-pin: none, render-single: auto, container-func: auto, container-args: (:))

A deixis-margin-note with default side: "outside", mark-align-strictness: "loose". Uses margin-note configuration and query type, without a separate sidenote engine. Set mark-align-strictness: auto to inherit configured strictness.

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.

marker-position

Mark marker placement.

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

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.

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.

layer

Rendering layer for the region mark. Choices: "flow" | "foreground" | "background".

See deixis-region-mark.layer.

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-margin-note(connector: (route: "right-angle", heads: "stealth"))[A connected note.]

width

The width of the margin note body.

See deixis-margin-note-body.width.

dx

Horizontal offset adjustment for the body.

See deixis-margin-note-body.dx.

dy

Vertical offset adjustment for the body.

See deixis-margin-note-body.dy.

side

Which margin to place the note in (left or right).

See deixis-margin-note-body.side.

side-strategy

Strategy to select side for margin note. Choices: "nearest" | "strict".

See deixis-margin-note-body.side-strategy.

mark-align

How the note aligns vertically relative to its mark.

See deixis-margin-note-body.mark-align.

mark-align-strictness

How strictly the engine attempts to keep the note exactly aligned with its mark. Choices: "strict" | "loose" | "none".

See deixis-margin-note-body.mark-align-strictness.

spillover

Allow this note to spill over page boundary.

See deixis-margin-note-body.spillover.

overflow

Keep out-of-frame placement (“allow”) or diagnose final margin bounds (“error”). The default is inherited; factory behavior is “allow”.

anchor-pin

A specific #deixis-pin name to anchor the body to, instead of the default layout logic.

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

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-sidenote-body

deixis-sidenote-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: 90%, dx: auto, dy: 0pt, side: "outside", side-strategy: auto, mark-align: auto, mark-align-strictness: "loose", spillover: auto, overflow: auto, anchor-pin: none, layer: auto, render-single: auto, container-func: auto, container-args: (:), ..args)

A deixis-margin-note-body with default side: "outside", mark-align-strictness: "loose". Uses margin-note configuration and query type. Explicit arguments override the preset; mark-align-strictness: auto inherits configured strictness.

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-margin-note(connector: (route: "right-angle", heads: "stealth"))[A connected note.]

width

The width of the margin note body. Defaults to 90% of the margin width.

//| sandbox-mode: "page"
#lorem(3)
#deixis-margin-note(width: 50%)[A narrow 50% note.]

dx

Horizontal offset adjustment for the body.

//| sandbox-mode: "page"
#deixis-margin-note(dx: -30pt)[A horizontally shifted note.]

dy

Vertical offset adjustment for the body.

Info.

dy is applied pre-layout, meaning that the final coordinates of the note can change after the rubber band pass.

//| sandbox-mode: "page"
#deixis-margin-note(dy: -50pt)[A vertically shifted note.]

side

Which margin to place the note in (left or right). If auto, uses the side nearest the mark.

//| sandbox-mode: "page"
#deixis-margin-note(side: left)[This is a left side note.]
#deixis-margin-note(side: right)[This is a right side note.]

side-strategy

Strategy to select side for margin note. Choices: "nearest" | "strict".

• With side-strategy: "nearest", notes will prefer the side that minimizes the vertical distance from the mark to the body.

//| sandbox-mode: "page"
#deixis-margin-note(side-strategy: "nearest")[Note A body.]
#deixis-margin-note(side-strategy: "nearest")[Note B body.]

• With side-strategy: "strict", notes will prefer the more visually favorable side until it is overflow.

//| sandbox-mode: "page"
#deixis-margin-note(side-strategy: "strict")[Note A body.]
#deixis-margin-note(side-strategy: "strict")[Note B body.]

mark-align

How the note aligns vertically relative to its mark.

• It can be an alignment or an equivalent str.

//| sandbox-mode: "page"
#lorem(8)
#deixis-margin-note(
  mark-align: bottom,
  connector: "right-angle",
  stroke: red,
  container-func: deixis-rect-container)[Top-aligned note body]

• Or a component-scope dictionary, only useful with mark-type: "region".

//| sandbox-mode: "page"
#deixis-margin-note(
  mark-type: "region",
  padding: "text",
  mark-align: (mark: horizon, body: horizon),
  connector: "right-angle",
  stroke: red,
  container-func: deixis-rect-container)[#lorem(8)][Horizon-aligned note body.]

mark-align-strictness

How strictly the engine attempts to keep the note exactly aligned with its mark. Choices: "strict" | "loose" | "none".

spillover

Allow this note to spill over page boundary.

//| sandbox-mode: "page"
#deixis-margin-note(spillover: false)[This is a very long note. #lorem(120)]
#deixis-margin-note(spillover: false)[This is another extremely long note. #lorem(120)]
#deixis-margin-note(spillover: true)[This is a spilled note.]

overflow

Keep out-of-frame placement (“allow”) or diagnose final margin bounds (“error”). The default is inherited; factory behavior is “allow”.

anchor-pin

A specific #deixis-pin name to anchor the body to, instead of the default layout logic.

//| sandbox-mode: "page"
#deixis-margin-note(
  anchor-pin: "pin0")[A note anchored to a pin.]
#lorem(20)
#deixis-pin("pin0")

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

layer

Body layer; flow is immediate placement with no spillover or collision pass.

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.