Deixis API Cheat Sheet

Deixis 0.2.0; Typst 0.15.0+. Names and selected defaults come from the public source through Tidy and the manual catalog. auto can resolve through scoped/factory settings. Grouped defaults belong to the first function; the website API pages show each full signature.

Setup: setup requires document setup; free needs none; conditional depends on document lookup; installs provides setup.

Setup And Defaults

Install setup before document annotations. Configuration can precede it. Reapply setup after replacing a native page foreground/background; identities and counters persist.

deixis-setup-notes

Document show rule: installs registration, references, visibility, validation and optional page overlays.

Setup: installs.

Selected parameters: override-page-footnotes = false; page-overlays = true; foreground = none; background = none.

Set page geometry/layers first. Page footnotes default to native flow; override-page-footnotes: true makes the foreground overlay their default. Host themes may install both overlay hooks with page-overlays: false.

deixis-page-overlay

Host integration hook for one page overlay; does not initialize the annotation registry.

Setup: setup.

Selected parameters: layer = "foreground".

Install background too: it records page geometry. See the setup guide for host-owned/scoped composition.

deixis-set / deixis-configure

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

Setup: free.

Selected parameters: omit = auto; palette = auto; numbering = auto; stroke = auto; marker-style = auto; connector = auto; layer = auto; render-single = auto.

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.

short

Opt-in module of short aliases. Use configure for settings and note-block for Deixis scopes; native block remains available.

Setup: free.

Import with #import "@preview/deixis:0.2.0": short as dx for qualified calls, or import short and then #import short: *. Wildcard aliases shadow native footnote/ref and math attach/arrowhead; use std.footnote, std.ref, std.math.attach and std.sym.arrowhead. configure avoids the set keyword; note-block preserves native block.

Marks And Identity

Use id to create the original counter owner; of reuses it. Names accept nonempty strings or labels. An original, its one body and reused marks may appear in any order. Reuse does not add a drawn connector.

deixis-mark

Unified original/reused mark. Defaults to inline; pins select region mode. A call without id/of is anonymous decoration.

Setup: setup.

Selected parameters: id = none; of = none; mark-type = auto; occurrence = none; marker = auto; numbering = auto.

mark-type: “region” highlights a passage or pins; “phantom” is a semantic origin. Set data on creation, not reuse. Resolved numbering: none takes no counter value; an explicit marker may still display. See shared options for styles, targets and region controls.

deixis-inline-mark

Specialized inline form of deixis-mark, with an optional marked passage.

Setup: setup.

Selected parameters: inline-mode = auto; marker-position = auto.

Box, highlight, underline, parentheses, text-fill and none are available. Reused marks retain the original styles beneath explicit overrides.

deixis-region-mark

Highlights a passage or a pin-defined region, with page-local fragment geometry.

Setup: setup.

Selected parameters: pins = (); padding = auto; layer = auto; inline = false; region-shape = auto.

Supply passage or pins, never both. A flow region must fit one page. Foreground/background regions may span pages. Region marker numerals remain foreground.

deixis-phantom-mark

Creates/reuses an invisible semantic original; its body may still carry a numbered marker.

Setup: setup.

Selected parameters: id = none; of = none; occurrence = none; marker = auto.

Phantom reuse accepts no passage or appearance overrides. An anonymous phantom draws nothing and consumes no palette slot.

Bodies And Collections

Wrappers accept [body] or [passage][body]. A -body call takes [body]. Wrapper id creates original + body; -body id creates a standalone body. With of, both forms attach only a body. Margin, inset and endnote bodies capture declaration typography; page footnotes use the native footer.

deixis-footnote / deixis-footnote-body

Allocates a native footer slot at the body declaration, even when its original mark is on another page.

Setup: setup.

Selected parameters: layer = auto; backlink = auto; container-args = (:).

Native flow (the default) paginates long bodies and uses the footer’s typography; separator/gap are native footnote.entry settings. Overlay footnotes reserve space but paint whole units. Local block footnotes collect at the block end. numbering: (restart: “page”, pattern: “1”) restarts displayed markers on each original page; assigned counts stay stable. HTML uses the native footnote section for every layer. Notes nested in Deixis footnote bodies exceed the HTML layout-pass budget.

deixis-margin-note / deixis-margin-note-body

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

Setup: setup.

Selected parameters: width = 90%; side = auto; dx = auto; dy = 0pt; spillover = auto; overflow = auto; mark-align = auto; mark-align-strictness = auto; anchor-pin = none.

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

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

Setup: setup.

Selected parameters: side = "outside"; mark-align-strictness = "loose".

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

deixis-comment

Review-comment preset: a margin note in the “review” series with lettered markers, author/status data and a bold header.

Setup: setup.

Selected parameters: author = none; status = none; series = "review"; numbering = "A"; header = auto.

Remove comments in the series for a final copy with deixis-set(omit: (series: ("review",))). Other options are margin-note options; of is rejected. Pass numbering: auto to inherit configured numbering, or numbering: none for no automatic marker and no counter value.

deixis-inset-note / deixis-inset-note-body

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

Setup: setup.

Selected parameters: width = auto; layer = auto; placement = none; dx = none; dy = none; anchor = (mark: horizon + right, body: horizon + left); anchor-pin = none.

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

deixis-inline-note / deixis-inline-note-body

An explanation in native flow: the wrapper places it right after its passage as an inline aside; a -body call places it where called.

Setup: setup.

Selected parameters: inline = true; of = none; breakable = true; container-args = (:).

The wrapper defaults to inline: true and keeps the sentence; inline: false gives a callout after the line (the -body default). Inline decoration bypasses block containers/custom single renderers. breakable: false supplies one frame for an explicit body endpoint.

deixis-endnote / deixis-endnote-body

Declares a collected explanation, rendered only by an eligible endnote printer.

Setup: setup.

Selected parameters: series = auto; backlink = auto; container-args = (:).

Wrapper series defaults to “endnote”; attachments inherit the original series. The printer controls where it appears. Body settings are retained until printing. Margin, inset, inline and footnotes nested in endnote bodies converge in PDF and HTML within the documented layout limits.

deixis-print-endnotes

Prints unprinted eligible bodies in source order; successive printers do not duplicate output.

Setup: setup.

Selected parameters: target = 0; series = auto; after = none; before = none; render-group = auto; container-args = auto.

Omitted overrides retain body settings. The grid bypasses per-note containers for default aligned singles; a series with a custom single renderer is stacked. Select deixis-native-render-group to use containers with default singles. after/before are exclusive source boundaries.

Connections And Drawing

A body connector is the short path for margin/inset notes. Independent edges select document endpoints without creating or moving them. Connections paint in their own foreground/background layer, below bodies at matching priorities.

deixis-connect

Draws an independent edge between marks, bodies, attached objects or pins; declarations may precede endpoints.

Setup: setup.

Selected parameters: from = none; to = none; connector = auto.

Bare from IDs select original marks; bare to IDs select bodies. Use (mark: id, occurrence: name), (body: id, point: “end”), (node: id) or (pin: target) explicitly. Default route is straight, or sharp orthogonal inside deixis-routing.

deixis-routing

Show-rule wrapper that captures a policy for individual connections and enabled margin/inset shorthand.

Setup: setup.

Selected parameters: policy = "separate"; nodes = (); clearance = 4pt; spacing = 3pt; rounds = 2; max-searches = 64.

manual keeps native routes; avoid searches independently; separate adds bounded group repair. Search needs sharp orthogonal geometry. Registered objects stay fixed. Nested wrappers form separate groups.

deixis-route

Builds source-local line/cubic geometry from finite absolute coordinates, optionally using a prepared scene.

Setup: free.

Selected parameters: from = none; to = none; route = "straight-line"; via = none; segments = none; radius = 0pt; scene = none; page = none.

Coordinates use x-right/y-down. origin is the source; segments are relative to it. No measurement or painting. Scene routes can fail: inspect status/detail before preparation. Avoidance requires sharp orthogonal paths.

deixis-routing-scene

Prepares reusable fixed rectangles/points in caller-defined page planes.

Setup: conditional.

Selected parameters: nodes = (); clearance = 4pt; escape = 4pt; bend-cost = 12pt; bounds = none; pages = ().

Numeric nodes need no setup. Selectors for document marks/bodies/pins need setup + context. Node behavior is avoid, ignore, cut or cross; the latter two do not add visual indicators.

deixis-route-group

Plans up to sixteen explicit sharp orthogonal page fragments together against a prepared scene.

Setup: free.

Selected parameters: edges (required); scene = none; spacing = 3pt; weight = 4; max-detour = 25%; rounds = 2; max-searches = 64; max-expansions = 50000.

Result routes retain input order. quality has before/after metrics; stats reports bounded work. No registration or painting. Complete separation/global optimality is not guaranteed. Preparing a document-derived scene still needs setup.

deixis-prepare-connector

Prepares existing geometry for native/custom paint without repeating routing. Head callbacks run here.

Setup: free.

Selected parameters: route (required); stroke = black + 1pt; heads = none; cuts = none; gap-marks = none.

Place the painted request at path.origin yourself. Relative styles/custom heads may need context. It consults no document defaults, page layer or automatic crossing group.

deixis-render-connector

Paints a prepared connector request, including shafts, heads and optional decorations.

Setup: free.

Selected parameters: request (required).

Numeric painting adds no layout dimensions; reserve the drawing area and place at the source origin. In document callbacks this is the default-painter delegation helper.

deixis-arrowhead

Constructs a reusable head specification; stealth is a filled triangular head with an open notch.

Setup: free.

Selected parameters: shape = "stealth"; length = auto; width = auto; fill = auto; stroke = auto; trim = auto; render = none.

Other native shapes include triangle, vee, circle, diamond and bar. Custom render(request) returns body, trim and bounds in a tip-local +x frame. Omitted dimensions scale with the shaft. Disable endpoint heads with heads: none.

deixis-render-head

Paints a prepared head in its local frame. A missing head or zero direction emits nothing.

Setup: free.

Selected parameters: head (required); tip (required); forward (required).

Use prepared heads from the connector request, not the raw specification returned by deixis-arrowhead.

Pins And Attachments

Pin names and attachment IDs accept string/label spellings. They have independent namespaces from note IDs. A pin is a point; an attached routing object registers one live, nonbreaking frame.

deixis-pin

Publishes a geometric anchor at its declaration; padding expands bounds around that anchor.

Setup: setup.

Selected parameters: name (required); scope = none; padding = "text"; extra-data = (:).

Default “text” padding follows local text metrics. Percentages have no pin-size basis. Scope namespaces pins independently of note/block identities.

deixis-attach

Wraps rendered content to attach pins, scan marked tokens, or register a selectable routing node.

Setup: setup.

Selected parameters: id = none; behavior = auto; pins = (:); scope = none; inline = false; padding = auto; pin-padding = (:).

id registers a routing frame with avoid behavior by default. Generated node ports are the four side midpoints. pins can define custom outlets. Explicit avoid/ignore/cut/cross also registers anonymous nodes. Pin-only attachments keep their native breakability.

Scopes And Counters

Scope names and note IDs are independent. Blocks own rendering instances and counter streams; thread shares a rendering domain, while counter synchronization only shares numbering.

deixis-block / deixis-minipage

Creates local annotation rendering/settings/counter scope around native content.

Setup: setup.

Selected parameters: id = auto; thread = none; sync-counters-with = auto; breakable = auto; width = auto; height = auto; inset = auto.

Minipage maps margin to internal inset and fixes outset at 0pt. Named IDs are unique; automatic scopes stay private. Breakable blocks use per-page margin frames and collect local footnotes at the block end. Page-local numbering restarts displayed markers at each original page, including inside multi-page blocks. HTML prints local footnote lists where their block ends.

deixis-note-counter

Reads the assigned counter value for a scope and literal series. Use inside context.

Setup: setup.

Selected parameters: target = 0; series = "default".

Unused streams start at zero. This is not a total annotation count. Page numbering resets do not reset note counters. Opt-in page-local display markers do not change this assigned value.

deixis-update-note-counter

Sets a stream to an integer or applies current → integer. The next numbered original increments that value.

Setup: setup.

Selected parameters: value (required); target = 0; series = "default".

Unnumbered originals, bodies, references and reuse never increment. Earlier notes keep assigned numbers. Endnote wrappers use the “endnote” series; select it explicitly for their resets.

References And Custom Views

Queries return safe semantic records and summaries instead of replaying live annotation content. An annotation remains one entry even when several marks share its body.

deixis-ref

References one or more annotations, retaining original marker styling and native fallback for ordinary labels.

Setup: setup.

Selected parameters: ..targets (required); supplement = auto; form = "normal"; marker-style = auto.

@detail uses the native bridge installed by setup. Repeated reference targets deduplicate; compatible numeric ranges can collapse. Explicit marker-style overrides formatting.

deixis-query-notes

One safe structured record per selected annotation. Page queries follow native body order; the unfiltered catalogue follows source order. Call inside context.

Setup: setup.

Selected parameters: target = auto; thread = auto; include-types = auto; series = auto; include-unpaired = auto; after = none; before = none; page = auto; order = auto.

Page queries include standalone bodies and require complete unique live spans. order: “source” / “body” and include-unpaired override automatic defaults. Each record retains all shared marks, safe summaries and optional body metadata; no live body content is returned.

deixis-note-outline

Ready-made linked list over the annotation catalogue; custom callbacks can replace summaries or presentation.

Setup: setup.

Selected parameters: title = [List of Notes]; include-types = auto; include-unpaired = false; group-by = none; summary = auto.

One entry per annotation, with links to all marked pages. Use query-notes for cards/tables or occurrence indexes. data can supply a custom title/status.

deixis-plain

Shows repeated content with its marked passages but without creating marks, bodies or connections again.

Setup: setup.

Selected parameters: body (required).

Native outlines apply it to heading and caption entries automatically. Use it for running headers and custom tables of contents that repeat annotated headings.

Rendering Extension Points

These hooks consume supplied records or content; they do not create a registered annotation. When used in live document annotations, keep setup active and preserve destination/content helpers. Relative typography and backlinks may require context.

deixis-native-render-single / deixis-aligned-render-single

Built-in single-body layouts. Native keeps a natural text flow; aligned accepts a shared marker column.

Setup: conditional.

Selected parameters: data (required); inner-width = auto.

Use supplied data unchanged when delegating. Aligned additionally accepts max-marker-width/max-marker-gap. The container and body-style come from the body record.

deixis-chicago-render-single

Chicago endnotes with a first-line indent and a full-size linked marker followed by a period.

Setup: conditional.

Selected parameters: data (required); inner-width = auto.

Defaults to a 0.5in first-line indent unless an explicit indent setting or printer override applies. Preserves inherited paragraph settings, backlinks, styles and containers. Unnumbered notes omit the marker and period. The default group stacks custom single renderers with the configured gap. HTML uses the native semantic renderer without paragraph indentation.

deixis-native-render-group / deixis-aligned-render-group / deixis-grid-render-group

Stack bodies, align stacked markers, or lay markers/content directly in two grid columns.

Setup: conditional.

Selected parameters: notes-data (required); gap = auto.

Native/aligned groups delegate to each single renderer. Grid paints default aligned records directly; a series with another single renderer is stacked natively. Containers alone do not change the grid path. Empty groups produce no content. Supplied records may contain live document behavior.

deixis-generate-body-meta / deixis-generate-body-marker / deixis-generate-body-content / deixis-generate-backlinks

Composable helpers for a custom body renderer: one destination, a marker, live content span, and return links.

Setup: conditional.

Selected parameters: data (required).

Emit meta OR marker once; marker already includes meta. Content publishes start/end spans and preserves nested palette ownership. Measurement records suppress live metadata. Backlinks read document origins and need setup/context.

deixis-plain-container / deixis-rect-container / deixis-alert-container

Body wrappers: identity, native rect alias, or a left-bar alert. Container arguments are forwarded separately from shared styles.

Setup: free.

Selected parameters: body (required); ..args (required).

container-func accepts "plain", "rect", "alert", "stripe" and "tinted", or a custom function. The first three select these exports; "stripe" and "tinted" are named accent presets. Explicit body stroke/fill/radius override preset styles; container-args supplies options such as inset. deixis-rect-container has native rect parameters. Alert doubles scalar border thickness on the left; native edge maps remain literal. Built-in containers emit plain text in HTML.

deixis-rect-region / deixis-ellipse-region

Region-shape callbacks for rectangular or elliptical bounds.

Setup: free.

Selected parameters: ..args (required).

Shape records provide width, height, fill/stroke and rectangle radius. Region registration/fragment selection belongs to the calling mark, not these painters. Use region marks with stroke: none for a highlight; add region-shape: deixis-ellipse-region for an ellipse.

Low-Level Layout Hooks

Advanced hooks use supplied measured records and geometry. Most documents should choose note adapters, container/render callbacks, or routing APIs instead. Native layout and document lookup are separate responsibilities.

deixis-margin-note-exact-layout / deixis-margin-note-adaptive-layout / deixis-margin-note-flow-layout

Numeric margin adapter hooks: exact ignores collisions; adaptive packs; flow distributes available space.

Setup: conditional.

Selected parameters: notes (required); top-bound (required); bottom-bound (required); start-x (required); text-width (required); end-y (required); left-space (required); right-space (required); current-page (required).

All share min-margin-width, pushed-notes and extra arguments. Supply accepted page geometry and prepared notes. They paint locally through the layout adapter. These hooks are not the body layer: “flow” switch.

deixis-place-anchored

Immediate placement relative to selected pin bounds on the call’s page.

Setup: setup.

Selected parameters: body (required); dx = 0pt; dy = 0pt; anchor = bottom + right; pin = none; body-size = auto.

Pin lookup reads document geometry. Native placement can disturb flow.

deixis-absolute-place

Immediate placement in physical page coordinates, ignoring margins.

Setup: conditional.

Selected parameters: ..args (required).

Accepts content, or alignment + content; dx/dy default to 0pt. Fixed page dimensions need no setup. An auto page axis needs setup-provided page frames for accepted dimensions. This is placement, not dimension reservation.