API Reference

deixis-margin-note

Overlay bodies follow the original mark or anchor pin; margin packing may spill onto later existing pages.

Setup Required

Returns: content.

Task guide

Example

deixis-margin-note(width: 30mm, side: right)[Passage][Explanation.]

Leave a wide page margin. Flow places exactly on the declaration page with no collision packing. overflow: “error” checks the final frame. Connector shorthand selects the original mark. HTML appends margin bodies to the document’s notes list.

deixis-margin-note

deixis-margin-note(..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: auto, side-strategy: auto, mark-align: auto, mark-align-strictness: auto, spillover: auto, overflow: auto, anchor-pin: none, render-single: auto, container-func: auto, container-args: (:))

A wrapper for generating margin notes.

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

//| sandbox-mode: "page"
The traveler felt a sudden sense of
#deixis-margin-note[fernweh][A deep, aching longing for far-off places; literally _farsickness_.]
as he watched the ships disappear beyond the horizon, bound for lands he had never seen.

• ..args (arguments): Accepts up to two positional arguments: [mark][body]. All named arguments are forwarded to deixis-margin-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.
• layer (auto, str): Rendering layer for the region mark. Choices: "flow" | "foreground" | "background".
• 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 margin note body. Defaults to 90% of the margin width.
• dx (auto, length): Horizontal offset adjustment for the body.
• dy (length): Vertical offset adjustment for the body. Defaults to 0pt.
• side (auto, alignment): Which margin to place the note in (left or right). If auto, uses the side nearest the mark.
• side-strategy (auto, str): Strategy to select side for margin note. Choices: "nearest" | "strict".
• mark-align (auto, alignment, dictionary): How the note aligns vertically relative to its mark.
• mark-align-strictness (auto, str): How strictly the engine attempts to keep the note exactly aligned with its mark. Choices: "strict" | "loose" | "none".
• spillover (auto, bool): Allow this note to spill over page boundary.
• overflow (auto, str, dictionary): Final margin-frame policy: “allow” or “error”.
• anchor-pin (none, str, dictionary): Pin name or structured target selecting one anchor occurrence.
• 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.

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-margin-note-body

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

A standalone body content of a margin note.

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

//| sandbox-mode: "page"
The old manor was a labyrinth of
#deixis-inline-mark(id: <crepuscular>)[crepuscular]
corridors, where the shadows seemed to stretch and breathe with the setting sun.

#deixis-margin-note-body(of: <crepuscular>)[Relating to or resembling twilight.]

• 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 margin note body. Defaults to 90% of the margin width.
• dx (auto, length): Horizontal offset adjustment for the body.
• dy (length): Vertical offset adjustment for the body. Defaults to 0pt.
• side (auto, alignment): Which margin to place the note in (left or right). If auto, uses the side nearest the mark.
• side-strategy (auto, str): Strategy to select side for margin note. Choices: "nearest" | "strict".
• mark-align (auto, alignment, dictionary): How the note aligns vertically relative to its mark.
• mark-align-strictness (auto, str): How strictly the engine attempts to keep the note exactly aligned with its mark. Choices: "strict" | "loose" | "none".
• spillover (auto, bool): Allow this note to spill over page boundary.
• overflow (auto, str, dictionary): Final margin-frame policy: “allow” or “error”.
• anchor-pin (none, str, dictionary): Pin name or (name:, scope:, select:, page:) target; one selected occurrence anchors the body.
• 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-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.