### Initialize Marginalia with Setup

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

The setup function is used as a show rule to configure margin dimensions, book-style layouts, and note clearance. This must be defined at the start of the document.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, notefigure, wideblock

#show: marginalia.setup.with(
  inner: (far: 5mm, width: 15mm, sep: 5mm),
  outer: (far: 5mm, width: 40mm, sep: 5mm),
  top: 2.5cm,
  bottom: 2.5cm,
  book: true,
  clearance: 12pt,
)
```

--------------------------------

### Setup and Configuration

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Instructions on how to import and configure the marginalia package in your Typst document.

```APIDOC
## Setup

Put something akin to the following at the start of your `.typ` file:

```typ
#import "@preview/marginalia:0.3.1" as marginalia: note, notefigure, wideblock

#show: marginalia.setup.with(
  // inner: ( far: 5mm, width: 15mm, sep: 5mm ),
  // outer: ( far: 5mm, width: 15mm, sep: 5mm ),
  // top: 2.5cm,
  // bottom: 2.5cm,
  // book: false,
  // clearance: 12pt,
)
```

If `book` is `false`, `inner` and `outer` correspond to the left and right margins respectively. If book is true, the margins swap sides on even and odd pages. Notes are placed in the outside margin by default.

Where you can then customize these options to your preferences. Shown here (as comments) are the default values taken if the corresponding keys are unset.

Additionally, I recommend using Typst's partial function application feature to customize other aspects of the notes consistently:

```typ
#let note = note.with(/* options here */)
#let notefigure = notefigure.with(/* same options here */)
```
```

--------------------------------

### Setup Typst Marginalia

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Initializes the marginalia package with custom layout settings. Users can define inner and outer margins, book mode, and clearance.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, notefigure, wideblock

#show: marginalia.setup.with(
  // inner: ( far: 5mm, width: 15mm, sep: 5mm ),
  // outer: ( far: 5mm, width: 15mm, sep: 5mm ),
  // top: 2.5cm,
  // bottom: 2.5cm,
  // book: false,
  // clearance: 12pt,
)
```

--------------------------------

### Configure Marginalia Document Layout

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

This snippet demonstrates how to initialize the Marginalia package using the setup show rule, configure page margins for book-style layouts, and define custom styling for notes and figures.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, notefigure, wideblock, notecounter

#set page(paper: "a4")
#show: marginalia.setup.with(
  inner: (far: 10mm, width: 20mm, sep: 8mm),
  outer: (far: 10mm, width: 35mm, sep: 8mm),
  top: 25mm,
  bottom: 20mm,
  book: true,
)

#let note = note.with(text-style: (size: 8pt))
#let notefigure = notefigure.with(text-style: (size: 8pt))
```

--------------------------------

### Configure Note Styling in Typst

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Demonstrates how to apply custom text, paragraph, and block styles to margin notes. It includes examples of static styling, background/border customization, and dynamic styling based on the margin side.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note

#show: marginalia.setup.with(
  outer: (far: 5mm, width: 40mm, sep: 5mm),
)

Text.#note(
  text-style: (size: 7pt, font: "Helvetica", style: "italic"),
  par-style: (spacing: 1.5em, leading: 0.6em),
)[Styled note with custom typography.]

Text.#note(
  block-style: (
    fill: rgb("#f0f8ff"),
    stroke: 0.5pt + blue,
    inset: 4pt,
    radius: 3pt,
  ),
)[Note with background and border.]

#let dynamic-note = note.with(
  block-style: side => {
    if side == "left" {
      (stroke: (left: none, rest: 0.5pt + purple), outset: (left: 10pt, rest: 4pt))
    } else {
      (stroke: (right: none, rest: 0.5pt + purple), outset: (right: 10pt, rest: 4pt))
    }
  },
)
Text.#dynamic-note[Style changes based on which margin it's in.]
```

--------------------------------

### Full Manual Link

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Link to the complete manual for detailed information.

```APIDOC
## Manual

[Full Manual →](https://github.com/nleanba/typst-marginalia/blob/v0.3.1/Marginalia.pdf?raw=true)
[![first page of the documentation](https://github.com/nleanba/typst-marginalia/raw/refs/tags/v0.3.1/preview.svg)](https://github.com/nleanba/typst-marginalia/blob/v0.3.1/Marginalia.pdf?raw=true)
```

--------------------------------

### Implement Margin Figures with Notefigure

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Explains how to use notefigure to place figures directly into the margin. Supports standard figure arguments, custom alignment, and styling.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: notefigure, notecounter

Text.#notefigure(
  rect(width: 100%, height: 30pt, fill: gradient.linear(blue, green)),
  caption: [A gradient rectangle in the margin.],
)<my-figure>

Text.#notefigure(
  rect(width: 100%, height: 25pt, stroke: purple),
  caption: [Styled figure.],
  block-style: (stroke: 0.5pt + purple, outset: 4pt),
  text-style: (size: 7pt, style: "italic"),
)
```

--------------------------------

### Configure Note Positioning and Side Selection

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Control note placement using the side parameter, vertical offsets with dy, and collision behavior with the shift parameter.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note

#show: marginalia.setup.with(
  inner: (far: 5mm, width: 20mm, sep: 5mm),
  outer: (far: 5mm, width: 40mm, sep: 5mm),
  book: true,
)

Text with inner note.#note(side: "inner")[This appears on the inner margin.]
Text with fixed side.#note(side: "left")[Always on left margin.]
Text with offset.#note(dy: 20pt)[This note starts 20pt below its anchor.]
Text with fixed note.#note(shift: false)[This note stays exactly at anchor position.]
Text.#note(shift: "avoid")[Only shifts if it would collide with a fixed note.]
```

--------------------------------

### Margin Notes

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

How to use the `#note` command to add notes to the margins, including labeling and customization.

```APIDOC
## Margin-Notes

Provided via the `#note[...]` command.

_New in version 0.3.0:_ Notes can be labeled and referenced: If you write `#note[]<xyz>`, then `@xyz` just works!

- `#note(side: "inner")[...]` to put it on the inside margin (left margin for single-sided documents).

  Also accepts: `auto`=`"outer"`, `"left"`, `"right"`.

- `#note(counter: none)[...]` to remove the marker.

  The display of the marker can be customized with the `numbering`, `anchor-numbering`, and `flush-numbering` parameters. Refer to the docs for details.

- `#note(shift: false)[...]` to force exact position of the note.

  Also accepts `auto` (behavior depends on whether it has a marker), `true`, `"avoid"` and `"ignore"`.

- And more options for fine control. All details are in the docs.
```

--------------------------------

### Create Basic Margin Notes

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

The note function places content in the margin. Notes automatically shift to avoid collisions with other elements.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note

#show: marginalia.setup.with(
  outer: (far: 5mm, width: 40mm, sep: 5mm),
)

This is regular text with a margin note.#note[
  This is a margin note. It can contain any content and will wrap
  within the note column automatically.
]

More text with another note.#note[A second note will shift to avoid the first.]
```

--------------------------------

### Retrieve Margin Configuration with get-left and get-right

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

These functions return the current page's margin configuration as a dictionary. This allows for precise custom positioning of elements relative to the defined margin widths and offsets.

```typst
#import "@preview/marginalia:0.3.1" as marginalia

#show: marginalia.setup.with(
  inner: (far: 10mm, width: 25mm, sep: 8mm),
  outer: (far: 10mm, width: 40mm, sep: 8mm),
  book: true,
)

#context {
  let left = marginalia.get-left()
  let right = marginalia.get-right()

  [Left margin width: #left.width]
  [Right margin width: #right.width]

  place(
    left,
    dx: left.far,
    rect(width: left.width, height: 20pt, fill: blue.lighten(80%)),
  )
}
```

--------------------------------

### Utility Functions

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Overview of utility functions provided by the marginalia package for advanced customization and referencing.

```APIDOC
## Utilities

- `#marginalia.header()` for easy two/three-column headers
- `#show: marginalia.show-frame` to show the page layout with background lines
- `#marginalia.note-numbering()` to generate your own numberings from sequences of symbols
- `#marginalia.ref()` to reference notes by relative index, without using labels.
- `#marginalia.get-left()` and `#marginalia.get-right()` to get contextual layout information.
```

--------------------------------

### Figures and Captions

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

How to integrate figures and customize their captions, including side captions and figures within wide blocks.

```APIDOC
## Figures

You can use figures as normal, also within wideblocks. To get captions on the side, use

1. If you want top-aligned captions:

```typ
#set figure(gap: 0pt) // neccessary in both cases
#set figure.caption(position: top)
#show figure.caption.where(position: top): note.with(
  alignment: "top", counter: none, shift: "avoid", keep-order: true,
  dy: -0.01pt, // this is so that the caption is placed above wide figures.
)
```

2. If you want bottom-aligned captions:

```typ
#set figure(gap: 0pt) // neccessary in both cases
#set figure.caption(position: bottom) // (this is the default)
#show figure.caption.where(position: bottom): note.with(
  alignment: "bottom", counter: none, shift: "avoid", keep-order: true)
```

### Figures in the Margin

For small figures, the package also provides a `notefigure` command which places the figure in the margin.

```typ
#notefigure(
  rect(width: 100%),
  caption: [A notefigure.],
)<figure-label>
```

It takes all the same options as `#note[]`, with some additions. In particular,

- You can use `#notefigure(note-label: <xyz>, ..)` to label the underlying note (if you want to reference it like a note)

- `#notefigure(show-caption: .., ..)` is how you change the caption rendering. NB.: this function is expected to take two arguments, please consult the docs.
```

--------------------------------

### Visualize Margin Boundaries with show-frame

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

The show-frame utility renders debug lines around margin boundaries. This is useful for verifying layout grids during document development and supports customization of stroke and header/footer visibility.

```typst
#import "@preview/marginalia:0.3.1" as marginalia

#show: marginalia.setup.with(
  inner: (far: 5mm, width: 20mm, sep: 5mm),
  outer: (far: 5mm, width: 40mm, sep: 5mm),
)

#show: marginalia.show-frame

#show: marginalia.show-frame.with(
  stroke: 1pt + red,
  header: false,
  footer: false,
)
```

--------------------------------

### Create Margin Figures

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Places a figure directly into the document margin using the notefigure command.

```typst
#notefigure(
  rect(width: 100%),
  caption: [A notefigure.],
)<figure-label>
```

--------------------------------

### marginalia.show-frame

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

A utility function to display debug lines showing margin boundaries for layout visualization.

```APIDOC
## FUNCTION marginalia.show-frame

### Description
Displays debug lines showing margin boundaries. Useful during document development to visualize the layout grid.

### Parameters
- **stroke** (stroke) - Optional - Customization of the frame line appearance.
- **header** (boolean) - Optional - Toggle visibility of header boundaries.
- **footer** (boolean) - Optional - Toggle visibility of footer boundaries.

### Request Example
#show: marginalia.show-frame.with(stroke: 1pt + red)
```

--------------------------------

### Layout Information Functions

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Functions to retrieve current page margin configuration for custom positioning.

```APIDOC
## FUNCTION marginalia.get-left / marginalia.get-right

### Description
Returns the contextual margin configuration (far, width, sep) for the current page.

### Response
- **Returns** (dictionary) - Contains keys: far (length), width (length), sep (length).
```

--------------------------------

### marginalia.note-numbering

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Generates marker symbols from configurable icon sequences for notes.

```APIDOC
## FUNCTION marginalia.note-numbering

### Description
Generates marker symbols from configurable icon sequences. Use with custom counters for varied marker styles.

### Parameters
- **number** (integer) - Required - The index to generate the marker for.
- **repeat** (boolean) - Optional - Whether to cycle through markers or switch to numbers.
- **markers** (array) - Optional - Sequence of symbols to use.
- **style** (function) - Optional - Styling function for the marker.

### Request Example
#note-numbering(repeat: false, markers: ("★", "☆"), 1)
```

--------------------------------

### Insert Marginal Notes and Figures

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

This snippet shows how to use the note, notefigure, and wideblock functions to place content in the margins or extend figures into the margin area.

```typst
This is main text.#note[Supplementary information in the margin.]

#notefigure(
  rect(width: 100%, height: 40pt, fill: gradient.linear(blue, cyan)),
  caption: [A small figure placed directly in the margin.],
  counter: notecounter,
)<small-fig>

#wideblock[
  #figure(
    rect(width: 100%, height: 80pt, fill: gradient.linear(purple, pink)),
    caption: [A wide figure extending into the margin.],
  )<wide-fig>
]
```

--------------------------------

### Configure Figure Captions

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Configures figure captions to appear in the margin using the note command. Supports both top and bottom aligned captions.

```typst
#set figure(gap: 0pt)
#set figure.caption(position: top)
#show figure.caption.where(position: top): note.with(
  alignment: "top", counter: none, shift: "avoid", keep-order: true,
  dy: -0.01pt,
)

#set figure.caption(position: bottom)
#show figure.caption.where(position: bottom): note.with(
  alignment: "bottom", counter: none, shift: "avoid", keep-order: true)
```

--------------------------------

### Wide Blocks

Source: https://github.com/nleanba/typst-marginalia/blob/main/README.md

Using the `#wideblock` command to extend content into the margins.

```APIDOC
## Wide Blocks

Provided via the `#wideblock[...]` command.

- `#wideblock(side: "inner")[...]` to extend into the inside margin instead.

  Also accepts: `auto`=`"outer"`, `"left"`, `"right"`, or `"both"`.

Note: Wideblocks do not handle pagebreaks well, especially in `book: true` documents. This is a limitation of Typst which does not (yet) provide a robust way of detecting and reacting to page breaks.
```

--------------------------------

### Generate Custom Note Markers with note-numbering

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

The note-numbering function creates marker symbols based on icon sequences. It supports alternating styles, non-repeating sequences, and custom styling for specialized note markers.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, note-numbering, note-markers, note-markers-alternating

#show: marginalia.setup.with(
  outer: (far: 5mm, width: 40mm, sep: 5mm),
)

#for i in range(1, 8) {
  note-numbering(i)
  [ ]
}

#note-numbering(repeat: false, markers: note-markers, 12)

#let star-numbering = note-numbering.with(
  markers: ("★", "☆", "✦", "✧"),
  style: text.with(fill: gold, size: 6pt),
)

#let star-note = note.with(numbering: star-numbering)
Text.#star-note[Uses star markers.]
```

--------------------------------

### marginalia.header

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Creates three-column headers that span into document margins, supporting even/odd page configurations.

```APIDOC
## FUNCTION marginalia.header

### Description
Creates properly sized three-column headers that span into margins. Supports positional arguments or specific even/odd page configurations.

### Parameters
- **...args** (content) - Optional - Up to three positional arguments for left, center, and right columns.
- **even** (dictionary) - Optional - Configuration for even pages.
- **odd** (dictionary) - Optional - Configuration for odd pages.
- **text-style** (dictionary) - Optional - Styling applied to the header text.

### Request Example
#marginalia.header[Left][Center][Right]

### Response
Returns content block formatted as a three-column header.
```

--------------------------------

### Customize Note Markers and Numbering

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Use custom counters and numbering functions to style note markers. You can also disable markers or differentiate between anchor and note numbering.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, notecounter

#let my-counter = counter("my-notes")
#let custom-note = note.with(
  counter: my-counter,
  numbering: (..i) => text(
    weight: 900,
    size: 5pt,
    fill: blue,
    numbering("A", ..i),
  ),
)

Regular note.#note[Uses default numbered marker.]
Custom note.#custom-note[Uses alphabetic marker A, B, C...]
Unnumbered.#note(counter: none)[No marker at all.]
```

--------------------------------

### Create Wide Blocks in Typst

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Shows how to use the wideblock function to extend content into the inner or outer margins. This is useful for wide tables or figures that exceed the standard text column width.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note, wideblock

#wideblock[
  This content extends into the outer/right margin.
]

#wideblock(side: "inner")[
  This extends into the inner/left margin instead.
]

#wideblock(side: "both")[
  This extends into both margins for maximum width.
]
```

--------------------------------

### Create Three-Column Headers with Marginalia

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

The header function generates three-column headers that span into document margins. It supports both positional arguments for simple headers and distinct even/odd page configurations.

```typst
#import "@preview/marginalia:0.3.1" as marginalia

#show: marginalia.setup.with(
  inner: (far: 5mm, width: 20mm, sep: 5mm),
  outer: (far: 5mm, width: 40mm, sep: 5mm),
  book: true,
)

#set page(
  header: context if here().page() > 1 {
    marginalia.header(
      text-style: (size: 9pt, style: "italic"),
      [Chapter 1],
      [Document Title],
      [Page #counter(page).display()],
    )
  },
)

#set page(
  header: marginalia.header(
    even: ([Page #counter(page).display()], [Title], [Section]),
    odd: ([Section], [Title], [Page #counter(page).display()]),
  ),
)

#marginalia.header[outer only]
#marginalia.header[center][outer]
#marginalia.header[inner][center][outer]
```

--------------------------------

### Reference Margin Notes

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Notes can be referenced using standard Typst labels or relative position offsets via the marginalia.ref function.

```typst
#import "@preview/marginalia:0.3.1" as marginalia: note

First note.#note[This is the first note.]<first-note>
Reference: @first-note

Text.#note[Note A]
Ref previous: #marginalia.ref(-1)
Ref next: #marginalia.ref(1)
Text.#note[Note B]<second-note>
```

--------------------------------

### Redirect Figure Captions to Margins

Source: https://context7.com/nleanba/typst-marginalia/llms.txt

Provides a pattern to move figure captions into the margin using show rules. This allows for full-width figures while keeping captions in the margin area.

```typst
#set figure.caption(position: bottom)
#show figure.caption.where(position: bottom): note.with(
  alignment: "bottom",
  counter: none,
  shift: "avoid",
  keep-order: true,
)

#figure(
  rect(width: 100%, height: 50pt, fill: gradient.linear(..color.map.viridis)),
  caption: [This caption appears in the margin aligned with the figure bottom.],
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.