API Reference

deixis-set

Updates subsequent defaults in the current Deixis scope; ordinary Typst brackets do not create a settings scope.

No Setup

Returns: content.

Task guide

Example

deixis-set(palette: "okabe-ito")

Top-level auto leaves settings unchanged. Type/component maps merge compatible branches; empty maps and branch auto have option-specific reset semantics. Resolved numbering: none takes no counter value; deixis-set(numbering: (footnote: "*")) selects a note family. Palette names are "deixis", "okabe-ito", "tol-bright", "tol-muted" and "tableau". omit: (series: ("todo",)) removes selected annotations while preserving passages; none includes all series. deixis-configure and short.configure are identical aliases.

deixis-set

deixis-set(omit: auto, palette: auto, numbering: auto, marker-style: auto, body-style: auto, backlink: auto, marker-position: auto, inline-mode: auto, stroke: auto, fill: auto, radius: auto, connector: auto, separator: auto, clearance: auto, gap: auto, marker-gap: auto, indent: auto, margin-layout: auto, min-margin-width: auto, side-strategy: auto, mark-align: auto, mark-align-strictness: auto, spillover: auto, overflow: auto, region-shape: auto, layer: auto, z-index: auto, render-single: auto, render-group: auto, container-func: auto)

Updates defaults within the current Deixis scope. Also available as deixis-configure and short.configure.

Defaults apply to subsequent declarations until the current deixis-block ends; outside a block they are document defaults. Ordinary Typst content brackets do not create a Deixis settings scope. Top-level auto arguments leave existing settings unchanged.

Tip.

Type-Specific Styling: Style parameters accept either a global value or a dictionary targeting specific note types (e.g., stroke: (margin-note: red, inset-note: blue)). A dictionary whose keys are all scope keys selects note types or components. Other dictionaries retain their native value shape; empty stroke/radius/position, connector, and arrowhead dictionaries are literal values.

• Type keys: inline-mark, phantom-mark, region-mark, footnote, endnote, margin-note, inset-note, inline-note, connection.

• Component keys: mark, body, connector.

  • "nodes" indicates both "mark" and "body" (excluding "connector").

• Wildcard key: "rest" indicates anything else. Body-only options (including renderers and containers) select the body/nodes branch automatically. Numbering/region shape select mark, and connector options select connector. Arrowhead mark/body maps describe endpoints. Repeated updates merge compatible dictionaries. Changing between native value and scope dictionaries, or between type and component scopes, replaces the old structure. An explicit empty dictionary clears it at that level. Route records (kind: ..., tension: ...) are complete literal values and replace atomically. String routes retain defaults; catmull-rom records can select centripetal/uniform parameterization. B-spline uses influence controls; Hobby uses global tension (minimum 0.75) and free-end curl (default 1). Controls belong to the algorithm. Sidenotes are margin-note presets; use margin-note settings, not sidenote keys.

• palette (auto, none, str, array): A built-in palette name or nonempty color sequence starts a fresh cycle in this Deixis scope; none disables later allocation and auto leaves it unchanged.

• numbering (auto, none, str, function, dictionary): The numbering style for markers; none disables automatic markers and counter allocation.

• marker-style (auto, function, dictionary): The styling function (content) => content for note markers.

• body-style (auto, function, dictionary): The styling function (content) => content for note bodies.

• backlink (auto, bool, str, dictionary): Enables or disables clickable backlinks from bodies to marks. Choices: bool | "always" | "none" | "never" | "multiple".

• marker-position (auto, alignment, dictionary): Mark marker placement.

• inline-mode (auto, str): The visual decoration applied to the marked inline text. Choices: "highlight" | "box" | "parentheses" | "underline" | "text-fill" | "none".

• stroke (auto, stroke, none, dictionary): The border stroke.

• fill (auto, color, none, dictionary): The background fill color.

• radius (auto, length, dictionary): The border radius.

• separator (auto, content, none, dictionary): The separator line for block footnote collections and endnotes.

• clearance (auto, length, dictionary): Vertical spacing before block footnote collections and endnotes.

• gap (auto, length, dictionary): Vertical spacing between adjacent notes.

• marker-gap (auto, length, dictionary): Horizontal spacing between the marker and the body text.

• indent (auto, length, dictionary): The indentation applied to the note body.

• margin-layout (auto, str): The layout engine for margin notes. Choices: "adaptive" | "flow" | "exact".

• min-margin-width (auto, length): Minimum margin width to put margin notes.

• side-strategy (auto, str): Strategy to select side for margin note. Choices: "nearest" | "strict".

• mark-align (auto, alignment, dictionary): How margin notes align vertically relative to their marks.

• mark-align-strictness (auto, str): How strictly to align margin notes to their marks. Choices: "strict" | "loose" | "none".

• spillover (auto, bool): Allow margin notes to spill over page boundaries.

• overflow (auto, str, dictionary): Margin frame policy: “allow” or “error” after final placement.

• region-shape (auto, function): Shape drawing function for region marks.

• layer (auto, str): The rendering layer for region marks and inset notes. Choices: "flow" | "foreground" | "background".

• render-single (auto, function, dictionary): Note body rendering function.

• render-group (auto, function, dictionary): Group rendering function for grouped notes (footnote and endnote).

• container-func (auto, str, function, dictionary): A named body container or function (content, ..args) => content.

Parameters

omit

Omit annotations created in these series, preserving marked passages. Omitted annotations have no counter, body, connector or query identity. Reused marks and attached bodies follow the original across scopes and forward declarations. References to omitted IDs are errors. Use none to include every series; auto leaves the policy unchanged.

palette

Optional annotation accent cycle. A color array or a built-in name (“deixis”, “okabe-ito”, “tol-bright”, “tol-muted”, “tableau”) starts a new cycle in the current Deixis scope; none disables it and auto leaves it unchanged. Reused marks/bodies keep the original accent; explicit styles win.

numbering

The numbering style for the marker. A literal (restart: "page", pattern: "1") uses the original mark’s physical page and restarts the displayed ordinal. Assigned counters/query counts stay unchanged; reuse and attached bodies keep the original marker, including inside multi-page blocks. HTML has no page boundaries and uses a continuous sequence. Ordinary strings/functions keep assigned numbering. Resolved none takes no counter value and shows no automatic marker; an explicit fixed marker may still display. Note-family keys such as (footnote: "*", endnote: "i") number the marks those wrappers create, ahead of mark-type keys and rest.

#deixis-set(numbering: "i")
#deixis-footnote[A note with roman numbering.]

marker-style

The styling function (content) => content for note markers.

#deixis-set(marker-style: (
  mark: it => text(super(it), fill: red),
  body: it => text([#it.], fill: blue, weight: "bold"))
)
#deixis-footnote[A note with custom mark marker style and body marker style.]

body-style

The styling function (content) => content for note bodies.

#deixis-set(body-style: it => text(it, fill: blue, weight: "semibold"))
#deixis-footnote[A note with custom body style.]

Info.

Setting body-style will override the default styling, i.e. it => text(size: 0.85em, it). Instead, applying custom styling directly to the body content does not.

#deixis-footnote[#text(fill: blue, weight: "semibold")[Another note with custom body style.]]

backlink

Enables or disables clickable backlinks from bodies to marks. Choices: bool | "always" | "none" | "never" | "multiple".

#deixis-set(backlink: true)
#deixis-footnote(id: <deixis-set.backlink>)[A note with backlink.]
#deixis-ref(<deixis-set.backlink>)

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.

stroke

The border stroke.

#deixis-inset-note(
  stroke: (mark: red, body: blue),
  layer: "flow",
)[A note with red mark stroke.][And blue body stroke.]

fill

The background fill color.

#deixis-inset-note(
  stroke: none,
  fill: (mark: red, body: blue),
  layer: "flow",
)[A note with red mark fill.][And blue body fill.]

radius

The border radius.

#deixis-inset-note(
  stroke: yellow,
  fill: yellow.transparentize(95%),
  radius: (mark: 0pt, body: 1em),
  layer: "flow",
)[A note with `0pt` mark radius.][And `1em` body radius.]

connector

Connector defaults for margin/inset notes and independent connections. A route name is shorthand for (route: name); a record sets any of route, ports, via/segments, heads, stroke, radius and the other connector fields. Records merge with outer defaults field by field; none disables. Routes: "none", "straight-line"/"polyline", "right-angle"/"orthogonal", "chamfer", "curve", "ccr", "ucr", "b-spline" and "hobby".

//| sandbox-mode: "page"
#deixis-set(connector: (route: "curve", heads: "stealth"))
#deixis-inset-note(dx: 4em, dy: 3em, layer: "flow")[Note mark.][Note body.]

Scope defaults by note type: connector: (margin-note: "curve").

separator

The separator line for note groups.

Info.

This affects local block footnote collections and endnote printers. Page footnotes share the native footer: configure it once with a document-level set footnote.entry(separator: ...), as for std.footnote.

#deixis-set(separator: line(length: 50%, stroke: (thickness: 0.5pt, dash: "dashed")))
#deixis-endnote[An endnote separated by a dashed line.]
#deixis-print-endnotes()

clearance

Vertical spacing before note groups.

Info.

This affects local block footnote collections and endnote printers. Page footnotes use the native footnote.entry clearance.

#deixis-set(clearance: 3em)
#deixis-endnote[A note `3em`-spaced from the main content.]
#deixis-print-endnotes()

gap

Vertical spacing between adjacent notes.

Info.

This affects margin notes, local block footnote collections and endnote printers. Page footnotes use the native footnote.entry gap.

#deixis-set(gap: 1em)
#deixis-endnote[Note A.]
#deixis-endnote[Note B.]
#deixis-print-endnotes()

marker-gap

Horizontal spacing between the marker and the body text.

#deixis-set(marker-gap: 1em)
#deixis-footnote[A note with `marker-gap=1em`.]

indent

The indentation applied to the note body.

#deixis-set(indent: 3em)
#deixis-footnote[A note with `indent=3em`.]

margin-layout

The layout engine for margin notes. Choices: "adaptive" | "flow" | "exact".

• "adaptive": Apply a two-pass rubber band algorithm to calculate the y-coordinates of all margin notes in the page; then use #std.place to put them into calculated positions.
• "flow": Distribute available space by fractional weights in a shared numeric plan, then place each note at its planned position.
• "exact": Put margin notes exactly where the marker is, ignore if they overlap or not.

min-margin-width

Minimum margin width to put margin notes.

//| margin: (left: 1.2in, right: 0.5in, y: 0.05in)
The margin of the minipage is set to `(left: 1.2in, right: 0.5in)`.
#deixis-set(min-margin-width: 1in)
#deixis-margin-note[This note prefers the left margin.]

side-strategy

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

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

mark-align

How margin notes align vertically relative to their marks.

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

mark-align-strictness

How strictly to align margin notes to their marks. Choices: "strict" | "loose" | "none".

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

spillover

Allow margin notes to spill over page boundaries.

See deixis-margin-note-body.spillover.

overflow

Margin body frame overflow: allow preserves placement; error checks final bounds.

region-shape

Shape drawing function for region marks.

See deixis-region-mark.region-shape.

layer

The rendering layer for region marks and inset notes. Choices: "flow" | "foreground" | "background".

See deixis-region-mark.layer.

z-index

Overlay paint priority. Higher integers paint later within a page layer. Native flow keeps its order; component/type dictionaries are supported.

render-single

Note body rendering function.

render-single formats each body; render-group arranges collected bodies. The examples use endnotes so both settings apply. Page footnotes use the native footer group and honor only their single renderer.

• native: Almost pixel-identical to std.footnote.

#deixis-set(
  render-single: deixis-native-render-single,
  render-group: deixis-native-render-group,
)
#deixis-endnote[A normal note.]
#deixis-endnote(marker: [long marker])[A note with very long marker, and also a long body.]
#deixis-print-endnotes()

• aligned: Body markers are aligned, but the notes are still prose-printed.

#deixis-set(
  render-single: deixis-aligned-render-single,
  render-group: deixis-aligned-render-group,
)
#deixis-endnote[A normal note.]
#deixis-endnote(marker: [long marker])[A note with very long marker, and also a long body.]
#deixis-print-endnotes()

• grid: Body markers and body content are structured in a grid.

#deixis-set(
  render-group: deixis-grid-render-group,
)
#deixis-endnote[A normal note.]
#deixis-endnote(marker: [long marker])[A note with very long marker, and also a long body.]
#deixis-print-endnotes()

Tip.

Custom renderers can combine deixis-generate-body-marker, deixis-generate-body-content and deixis-generate-backlinks. Emit the body content helper once to preserve navigation spans and nested annotations.

#let custom-render-func(note-data, ..args) = {
  let body-marker = deixis-generate-body-marker(note-data + (body-marker-style: it => it))
  rect(
    ..note-data.styles,
    inset: (top: 10pt, rest: 5pt)
  )[
    #place(center + top, dy: -20pt, rect(
      stroke: note-data.styles.stroke,
      fill: white,
      radius: 1em,
      body-marker))
    #deixis-generate-body-content(note-data)
  ]
}

#deixis-set(
  render-single: custom-render-func,
  render-group: deixis-native-render-group,
)
#deixis-footnote[A note with custom render function.]

render-group

Group rendering function for grouped notes (footnote and endnote).

See deixis-set.render-single.

container-func

A body-container name (“plain”, “rect”, “alert”, “stripe”, “tinted”) or function (content, ..args) => content. Type/component maps are supported. “stripe” and “tinted” use the annotation accent; explicit body styles win. Forward native/custom wrapper options through container-args on the note.

#import "@preview/colorful-boxes:1.4.3": stickybox
#deixis-set(container-func: (body, ..args) => stickybox(body))
#deixis-margin-note(target: "page")[Yes, we can also do that.]

Tip.

container-func is only a wrapper around the rendered body of each note and does not have access to the raw notes’ data. For more sophisticated control, you should use deixis-set.render-single or deixis-set.render-group.

deixis-configure

deixis-configure

Alias of deixis-set: updates defaults within the current Deixis scope. Both prefixed names are the same function. The short module exports configure, since set is a Typst keyword.