API Reference

deixis-region-mark

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

Setup Required

Returns: content.

Example

deixis-region-mark(inline: true)[$x^2 + y^2$]

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-region-mark

deixis-region-mark(..args, id: none, data: (:), of: none, occurrence: none, pins: (), numbering: auto, marker: auto, target: 0, series: "default", marker-style: auto, marker-position: auto, stroke: auto, fill: auto, radius: auto, z-index: auto, padding: auto, region-shape: auto, layer: auto, inline: false)

A visual enclose mark of a specific region in the document.

Region marks are highly versatile. They can dynamically wrap a continuous block of text provided as a positional argument, or they can asynchronously draw a shape spanning between pre-defined #deixis-pin coordinates. They support crossing page boundaries with background/foreground layers, including automatic corner pins around breakable block content. With of: id, it creates another region occurrence of an existing annotation. Its own pins/content determine geometry; the original still owns the number, body placement, and implicit connector. Name it with occurrence for an explicit connection, including automatic page-fragment selection.

Inline marks cannot highlight equations or `raw`:

#deixis-inline-mark[*Sigmoid:* $f(x) = frac(1, 1 + e^(-x))$ or `torch.sigmoid`.]

This is where region marks shine:

#deixis-region-mark(inline: true)[*ReLU:* $f(x) = max(0, x)$ or `torch.relu`]

#let highlight-cell = deixis-region-mark.with(stroke: blue, fill: blue.transparentize(95%))

#set text(0.8em)
#table(
  columns: (auto, 1fr, auto, 1fr),
  align: center + horizon,
  fill: (x, y) => if y == 0 { gray.lighten(80%) },

  table.header([*Function*], [*Equation*], [*Output\ Range*], [*Common\ Usecase*]),
  [*Sigmoid*], [$1 / (1 + e^(-x))$], [$(0, 1)$], [Binary classifier],
  [*Tanh*], [$(e^x - e^(-x)) / (e^x + e^(-x))$], [$(-1, 1)$], [RNNs],
  [*ReLU*], [$max(0, x)$], [$[0, inf)$], [CNNs],
  [*GELU*], highlight-cell(padding: 4pt)[$x Phi(x)$], [$approx [-0.17, inf)$], [*Transformers*],
)

..args (arguments): Accepts at most 1 positional argument: [body].
id (none, str, label): The unique identifier linking this region to its data/body state.
data (dictionary): Custom annotation fields, kept under note.data. Configure on creation or a standalone body; omit with of.
pins (array): Pin names or (name:, scope:, select:, page:) targets. Strings combine all occurrences; records default to a unique match. Cannot be used simultaneously with a positional body.
numbering (auto, none, str, function, dictionary): The numbering style for the region’s marker.
marker (auto, content): A hardcoded marker to use instead of the automatic counter.
target (int, label, str): The specific block/minipage counter context this mark belongs to.
series (str): The counter series this mark belongs to.
marker-style (auto, function): A custom styling function (string) => content for the generated marker.
marker-position (auto, alignment, dictionary): Where to place the marker relative to the bounding box.
stroke (auto, stroke, none): The border stroke of the region highlight.
fill (auto, color, none): The background fill color of the region highlight.
radius (auto, length, dictionary): The border radius of the region shape. Automatically adjusts when breaking across pages.
padding (auto, length, str): The padding between the highlighted text and the border. Using "text" aligns to font metrics.
region-shape (auto, function): Shape drawing function.
layer (auto, str): The rendering layer context. Choices: "flow" | "foreground" | "background".
inline (bool): If true, the region wraps the text in an inline box instead of a standard block.

Parameters

Name	Default	Types
`..args`	variadic	arguments
`id`	`none`	none, str, label
`data`	`(:)`	dictionary
`of`	`none`	none, str, label
`occurrence`	`none`	none, str, label
`pins`	`()`	array
`numbering`	`auto`	auto, none, str, function, dictionary
`marker`	`auto`	auto, content
`target`	`0`	int, label, str
`series`	`"default"`	str
`marker-style`	`auto`	auto, function
`marker-position`	`auto`	auto, alignment, dictionary
`stroke`	`auto`	auto, stroke, none
`fill`	`auto`	auto, color, none
`radius`	`auto`	auto, length, dictionary
`z-index`	`auto`	auto, int, dictionary
`padding`	`auto`	auto, length, str
`region-shape`	`auto`	auto, function
`layer`	`auto`	auto, str
`inline`	`false`	bool

..args

Accepts at most 1 positional argument: [body].

id

The unique identifier linking this region to its data/body state.

data

Custom annotation fields, owned by the original. Omit with of.

of

Reuse an annotation with new region geometry, without a new number/body.

occurrence

Optional occurrence name, scoped to the reused annotation.

pins

Pin names or structured targets, e.g. ((name: "corner", scope: "diagram"),). Strings combine all occurrences. Records require a match and default to unique selection; select can be all, first, last, or unique, and page can restrict to a positive physical page number. Cannot also wrap a body.

See deixis-pin and deixis-attach.

If alignment, align to one of the 9 locations.

#deixis-region-mark(
  id: <celibate-region1>,
  marker-position: top + center)[#lorem(10)]

If dictionary of length or relative, place the mark at (dx, dy) relative to the top left corner of the region. relative is understood as to the dimensions of the region.

#deixis-region-mark(
  id: <celibate-region2>,
  marker-position: (dx: 100% + 5pt, dy: 5pt))[#lorem(10)]

*Kepler’s First Law of Planetary Motion* states that every planet’s orbit is an ellipse:
#align(
  center,
  deixis-region-mark(padding: (x: 8pt, y: 8pt), region-shape: deixis-ellipse-region)[$r = frac(1 - e^2, 1 + e cos(theta))$]
)

layer

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

With "foreground" layer, the region is rendered in the foreground of the page, and may occlude the highlighted content.
With "background" layer, the region will be rendered in the background of the page, and might be occluded by other contents.

// pins already placed in manual.typ
This example draws the #box(width: 0.6em, height: 0.6em, stroke: yellow) yellow region around this documentation chapter.
#deixis-region-mark(
  pins: ("region-mark-chapter-start", "region-mark-chapter-end"),
  padding: (x: 5pt, top: -5pt, bottom: 5pt),
  stroke: yellow + 2pt,
  fill: yellow.transparentize(98%),
  radius: 10pt,
  layer: "background",
)

With "flow" layer, the placement of the region is synchronuous.

#deixis-region-mark(
  pins: ("test-layer3", "test-layer4"),
  stroke: none,
  fill: purple.transparentize(25%),
  layer: "flow",
)  // below the highlighted text

#quote(attribution: [Messmer the Impaler], block: true)[*#deixis-pin("test-layer1")Mongrel#deixis-pin("test-layer2") #deixis-pin("test-layer3")intruder#deixis-pin("test-layer4").*]

#deixis-region-mark(
  pins: ("test-layer1", "test-layer2"),
  stroke: none,
  fill: red.transparentize(25%),
  layer: "flow",
)  // above the highlighted text

Tip.

Use "flow" for highlighting images, diagrams, … Be aware that it will trigger a #parbreak.
Use "background" for highlighting texts, equations, … if they are not in a non-transparent container.
Use "foreground" or "background" where the region can span across multiple pages.

inline

If true, the region wraps the text in an inline box instead of a standard block.

Keyboard shortcuts

Deixis