### Minimal Drafting Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

A basic Typst document demonstrating the setup and usage of the drafting package, including page configuration and adding a margin note.

```typst
#import "@preview/drafting:0.2.2": *

// Set up the page with margins
#set page(margin: 2cm)

// Configure drafting for your page layout
#set-page-properties()

// Now you can add notes
#lorem(20)
#margin-note[This is a comment in the margin]
#lorem(20)
```

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

### Install showman

Source: https://github.com/ntjess/typst-drafting/blob/main/release-instructions.md

Install the showman tool using pip. This tool is used for packaging assets for the release.

```sh
pip install showman
```

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

### Required Drafting Setup

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Essential setup steps for using margin notes: setting page margins and calling `set-page-properties()`.

```typst
#set page(margin: 2cm)
#set-page-properties()
```

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

### Test with Minimal Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/errors.md

Isolate potential issues by creating a minimal working example. This helps determine if the problem lies in your specific configuration or the package itself.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()
#margin-note[Test]
```

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

### Basic Page Setup with set-page-properties

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-page-properties.md

Demonstrates the basic usage of set-page-properties to apply standard margins and enable margin notes.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#lorem(20)
#margin-note[Notes now work correctly]
#lorem(20)
```

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

### Early Configuration Setup

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Set up page properties and default configurations early in the document. This ensures consistent styling from the beginning of the document.

```typst
#set page(margin: 2cm)
#set-page-properties()
#set-margin-note-defaults(stroke: blue)
// Now create notes
```

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

### Basic Typst Drafting Setup

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/INDEX.md

Import the drafting package and set basic page properties. This is the foundational setup for using the package.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()
```

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

### Import and Setup Drafting Package

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/README.md

Import the drafting package and set default page properties. Ensure the package version is specified.

```typst
#import "@preview/drafting:0.2.2": *

#set page(margin: 2cm)
#set-page-properties()
```

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

### Install Drafting Package

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Import the drafting package from the official Typst preview namespace. Ensure you are using a compatible Typst version.

```typst
#import "@preview/drafting:0.2.2": *
```

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

### Basic Grid with Spacing

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-rule-grid.md

Creates a basic grid with specified width, height, and spacing. Use this for general layout guides.

```typst
#import "@preview/drafting:0.2.2": *

#rule-grid(width: 10cm, height: 3cm, spacing: 20pt)
#v(3cm + 1em)  // Account for grid height
```

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

### Multiple Reviewer Setup with Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-margin-note-defaults.md

Sets up distinct margin note styles for multiple reviewers by creating functions that pre-configure the `margin-note` macro with specific strokes.

```typst
#let reviewer-a = margin-note.with(stroke: blue)
#let reviewer-b = margin-note.with(stroke: purple)
#let reviewer-c = margin-note.with(stroke: green)

#reviewer-a[Comment from reviewer A]
#reviewer-b[Comment from reviewer B]
#reviewer-c[Comment from reviewer C]
```

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

### Custom Rect Function Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Demonstrates using a custom `rect` function to render the border of an inline note. This example imports a `stickybox` function from the `colorful-boxes` library and applies a rotation and auto width.

```typst
#import "@preview/colorful-boxes:1.1.0": stickybox

#let custom-rect = stickybox.with(rotation: 30deg, width: auto)
#inline-note(rect: custom-rect)[Sticky note style]
```

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

### RTL Document Setup

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-page-properties.md

Demonstrates automatic detection of Right-to-Left (RTL) text direction and its effect on page binding when using `set-page-properties`.

```typst
#set text(lang: "ar")
#set page(margin: 2.5cm)
#set-page-properties()
// Automatically detects RTL and sets binding accordingly
```

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

### Dashed Stroke Pattern Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Shows how to apply a dashed stroke pattern to an inline note using the `stroke` parameter with a `dash` property. This example also uses `par-break: false` to keep the note inline.

```typst
#inline-note(
  par-break: false,
  stroke: (paint: orange, dash: "dashed")
)[Dashed border inline note]
```

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

### Comparing Different Margin Configurations

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-place-margin-rects.md

A helper function `show-margin-config` is used to compare different page margin setups and visualize them with `place-margin-rects`. This aids in understanding the impact of various margin settings.

```typst
#let show-margin-config(title, margin-setup, show-rects: true) = {
  heading(level: 2, title)
  set page(..margin-setup, width: 15cm, height: 10cm)
  set-page-properties()
  
  if show-rects {
    place-margin-rects(fill: gray.lighten(80%), opacity: 50%)
  }
  
  margin-note[Sample note]
  lorem(10)
}

#show-margin-config("2cm margins", (margin: 2cm))
#pagebreak()
#show-margin-config("3cm left, 1cm right", (margin: (left: 3cm, right: 1cm)))
```

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

### Custom Rect Function Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/types.md

Demonstrates how to define and use custom functions for rendering rectangles, such as creating a rounded badge shape. This allows for flexible customization of element appearances.

```typst
#let rounded-rect = rect.with(radius: 0.5em)
#set-margin-note-defaults(rect: rounded-rect)

// Or with a fully custom function:
#let badge-rect(stroke: none, fill: none, width: 0pt, content) = {
  box(
    fill: fill,
    stroke: stroke,
    radius: 50%,
    width: width,
    content
  )
}
#set-margin-note-defaults(rect: badge-rect)
```

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

### Styled Inline Note Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Illustrates styling an inline note with custom stroke (color and thickness) and fill (background color). The note's content is highlighted.

```typst
#inline-note(
  stroke: orange + 3pt,
  fill: yellow.lighten(80%)
)[Important information highlighted inline]
```

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

### Different Padding for Margin Rects

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-place-margin-rects.md

Apply different padding values to the margin rectangles to visually distinguish them. This example uses points for precise control.

```typst
#place-margin-rects(
  padding: 5pt,
  fill: yellow.lighten(70%)
)
#lorem(100)
```

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

### Mixed Paragraph and Inline Notes Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Combines both paragraph-breaking and inline notes within the same document flow to show their distinct behaviors and how they can be interleaved with regular text.

```typst
#lorem(5)
#inline-note[This breaks the paragraph]
#lorem(5)
#inline-note(par-break: false)[This stays inline] #lorem(5)
#inline-note[Back to paragraph breaking]
#lorem(5)
```

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

### Inline Mode Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Shows how to use inline_note with `par-break: false` to embed a note directly within the text flow, without breaking the paragraph. Includes surrounding lorem ipsum text for context.

```typst
#lorem(10)
#inline-note(par-break: false)[This note stays inline with text]
#lorem(10)
```

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

### Typst Stroke Examples

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/types.md

Illustrates various ways to define strokes for elements like margin notes, from simple colors to complex objects with custom properties like dash patterns and join styles.

```typst
// Simple color
#margin-note(stroke: red)[Note]
```

```typst
// With thickness
#margin-note(stroke: red + 2pt)[Note]
```

```typst
// With dash pattern
#margin-note(stroke: (paint: orange, dash: "dashed"))[Note]
```

```typst
// Complex stroke
#margin-note(stroke: (
  paint: blue,
  thickness: 2pt,
  dash: "dotted",
  join: "round"
))[Note]
```

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

### Repeating Elements Across Pages

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-absolute-place.md

Defines a reusable `absolute-place` configuration for consistent element placement on multiple pages, such as page numbers. The example shows placing page numbers near the bottom center.

```typst
#let page-number-marker = absolute-place.with(
  dx: 10.5cm, // Center horizontally on A4
  dy: 28.5cm // Near bottom
)

#page-number-marker(text(size: 10pt, "Page 1"))
#pagebreak()
#page-number-marker(text(size: 10pt, "Page 2"))
#pagebreak()
#page-number-marker(text(size: 10pt, "Page 3"))
```

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

### Typst Numbering Type Examples

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/types.md

Demonstrates setting default and custom numbering styles for margin notes using the `numbering` function. The `auto` keyword uses the default style, while custom functions allow for specific formatting.

```typst
#set-margin-note-defaults(inline-numbering: auto)

// Custom style: shows as [1], [2], etc.
#set-margin-note-defaults(inline-numbering: i => [*[#i]*])

// Custom style: shows as TODO 1:, TODO 2:, etc.
#set-margin-note-defaults(note-numbering: i => [*TODO #i:* ])
```

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

### Package assets for release

Source: https://github.com/ntjess/typst-drafting/blob/main/release-instructions.md

Use showman to bundle assets for the new release. Ensure the --typst_packages_folder points to the correct directory containing the 'preview' folder.

```sh
showman package ./typst.toml \
    --typst_packages_folder /path/to/typst/packages/packages/ \
    --namespace preview \
    --overwrite
```

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

### Apply Local Margin Note Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Demonstrates scoping configuration changes using blocks. Changes made within a block do not affect settings outside the block.

```typst
#set-margin-note-defaults(stroke: red)
#margin-note[Red note]

// Local scope using a block
{
  #set-margin-note-defaults(stroke: blue)
  #margin-note[Blue note]
}

#margin-note[Red note again]
```

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

### Create Margin and Inline Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/README.md

Demonstrates how to create notes in the margin and inline within the text. Includes generating a note outline.

```typst
#margin-note[Comment in margin]
#inline-note[Comment in text]
#note-outline()
```

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

### Update Default Margin Note Styles

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Customize the default appearance of all margin notes by updating module state. This example changes the stroke color and side.

```typst
#lorem(14) #margin-note[Default style]
#lorem(10)
#set-margin-note-defaults(stroke: orange, side: left)
#margin-note[Updated style]
#lorem(10)
```

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

### Set Page Margins for Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Configure page margins to control the layout space for margin notes. This example sets the left margin to 2cm.

```typst
// Example:
// Default margin in typst is 2.5cm, but we want to use 2cm
// On the left
#set-page-properties(margin-left: 2cm)
```

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

### Create Margin Note Variants with .with()

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Create reusable variants of margin notes with predefined styles using the `.with()` method. This allows for quick application of different note types.

```typst
#let editor-note = margin-note.with(stroke: blue, side: left)
#let author-note = margin-note.with(stroke: red, side: right)
#let reviewer-note = margin-note.with(stroke: green)
```

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

### Two-Part Margin Notes with Inline Highlighting

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note.md

Explains how to create two-part margin notes where the first part is the main note and the second part provides an inline explanation or highlighting.

```typst
#margin-note[important keyword][Explanation of why this keyword matters]
```

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

### Get Current Margin Note Defaults

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note-defaults.md

Retrieves the current default settings for margin notes. This is useful for inspecting or saving the current configuration before making changes.

```typst
#context {
  let defaults = margin-note-defaults.get()
  let current-stroke = defaults.stroke
  let current-fill = defaults.fill
}
```

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

### Basic Margin Visualization

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-place-margin-rects.md

Use this to visualize the default page margins with a light gray fill. Ensure the `@preview/drafting` package is imported and page properties are set.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm, width: 21cm)
#set-page-properties()

#place-margin-rects(fill: gray.lighten(80%))
#lorem(100)
```

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

### Basic Margin Note and Outline

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-note-outline.md

Demonstrates the basic usage of margin notes and generating a note outline. Ensure the 'drafting' package is imported and page properties are set.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#margin-note[First annotation]
#lorem(50)
#margin-note[Second annotation]
#lorem(50)

#note-outline()
```

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

### Deep Customization of Margin Note Rect

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Override the default rectangle used for margin notes for advanced styling. This example uses a 'stickybox' with custom rotation and scaling.

```typst
#import "@preview/colorful-boxes:1.1.0": stickybox

#let default-rect(stroke: none, fill: none, width: 0pt, content) = {
  stickybox(rotation: 30deg, width: width/1.5)[
    #set text(0.9em)
    #content
  ]
}
#set-margin-note-defaults(rect: default-rect, stroke: none, side: right)

#lorem(20)
#margin-note(dy: -5em)[Why not use sticky notes in the margin?]

// Undo changes from this example
#set-margin-note-defaults(rect: rect, stroke: red)
```

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

### Add and commit changes

Source: https://github.com/ntjess/typst-drafting/blob/main/release-instructions.md

Stage all modified files and commit them with a descriptive message. This prepares the changes for version control.

```sh
git add .
git commit -m "Update readme for release"
```

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

### Absolute Placement with Rule-Grid

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-absolute-place.md

Demonstrates how to use `absolute-place` in combination with `rule-grid` to position elements accurately on a page. The `rule-grid` helps visualize the coordinate system, and `absolute-place` then places content at specified `dx` and `dy` offsets.

```APIDOC
## absolute-place(dx, dy, body)

### Description
Places content at an absolute position on the page, relative to the top-left corner.

### Parameters
#### Path Parameters
- **dx** (length) - Required - The horizontal offset from the page's left edge.
- **dy** (length) - Required - The vertical offset from the page's top edge.
- **body** (content) - Required - The content to be placed.

### Request Example
```typst
#absolute-place(dx: 5cm, dy: 7.5cm, circle(radius: 5mm, fill: red))
```

### Important Notes
- This function must be called within a context block.
- Coordinates are relative to the current page and reset for each page.
- Absolutely positioned content does not have a bounding box in the document layout.
```

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

### Custom Rectangular Style for Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Define and apply a custom rectangular style for margin notes using `stickybox` from the `colorful-boxes` package. This example rotates the box and sets stroke to none.

```typst
#import "@preview/colorful-boxes:1.1.0": stickybox

#let sticky-rect(stroke: none, fill: none, width: 0pt, content) = {
  stickybox(rotation: 30deg, width: width/1.5)[
    #set text(0.9em)
    #content
  ]
}

#set-margin-note-defaults(rect: sticky-rect, stroke: none)
```

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

### Basic Inline Note Usage

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Demonstrates creating inline notes. By default, they split the paragraph at their location.

```typst
#lorem(10)
#inline-note[The default inline note will split the paragraph at its location]
#lorem(10)
```

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

### Manually Adjusting Overlapping Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/errors.md

When 5 or more margin notes overlap, Typst may issue a warning. This example shows how to manually shift notes using 'dy' to resolve overlaps.

```typst
#margin-note(dy: -2em)[Manually shifted up]
#margin-note(dy: -1em)[Another manual shift]
#margin-note(dy: 0em)[Third note]
#margin-note(dy: 1em)[Fourth note]
#margin-note(dy: 2em)[Fifth note - manual adjustment needed]
```

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

### Paragraph Break Mode Example

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-inline-note.md

Demonstrates using inline_note with `par-break: true` to create a note that breaks the paragraph and appears on its own line. Requires importing the drafting library and setting page margins.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#lorem(10)
#inline-note[This is a paragraph-breaking inline note]
#lorem(10)
```

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

### Basic Margin Note Usage

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Demonstrates creating margin notes with different content and automatic collision avoidance. Includes notes with specified sides and strokes.

```typst
#lorem(20)
#margin-note(side: left)[Hello, world!]
#lorem(10)
#margin-note[Hello from the other side]
#margin-note[When notes are about to overlap, they're automatically shifted]
#margin-note(stroke: aqua + 3pt)[To avoid collision]
#lorem(25)
#margin-note(stroke: green, side: left)[You can provide two positional arguments if you want to highlight a phrase associated with your note.][The first is text which should be inline-noted, and the second is the standard margin note.]

#let caution-rect = rect.with(inset: 1em, radius: 0.5em)
#inline-note(rect: caution-rect, fill: orange.lighten(80%))[
  Be aware that `typst` will complain when 4 notes overlap, and stop automatically avoiding collisions when 5 or more notes
  overlap. This is because the compiler stops attempting to reposition notes after a few attempts
  (initial layout + adjustment for each note).

  You can manually adjust the position of notes with `dy` to silence the warning.
]
```

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

### Precise Page Placement with Rule Grid in Typst

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Employ `#rule-grid` for fine-tuned positioning by cross-hatching the page. Specify dimensions and spacing for grid lines. The grid itself does not occupy space, so manual vertical spacing might be needed.

```typst
#rule-grid(width: 10cm, height: 3cm, spacing: 20pt)
#place(
  dx: 180pt,
  dy: 40pt,
  rect(fill: white, stroke: red, width: 1in, "This will originate at (180pt, 40pt)")
)

// Optionally specify divisions of the smallest dimension to automatically calculate
// spacing
#rule-grid(dx: 10cm + 3em, width: 3cm, height: 1.2cm, divisions: 5, square: true,  stroke: green)

// The rule grid doesn't take up space, so add it explicitly
#v(3cm + 1em)
```

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

### Troubleshooting: Notes Not Appearing

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Ensures margin notes appear by verifying that `set-page-properties()` is called after setting page margins.

```typst
#set page(margin: 2cm)
#set-page-properties()  // Required!
#margin-note[This will appear]
```

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

### Update readme script

Source: https://github.com/ntjess/typst-drafting/blob/main/release-instructions.md

Run the update_readme.sh script to generate the README.md file. Initially, comment out --git_url to include images directly. Uncomment and update the tag later to link to GitHub assets.

```sh
./update_readme.sh
```

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

### Measuring Content Placement

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-rule-grid.md

Demonstrates placing content at specific coordinates within a grid using `dx` and `dy`. Useful for precise element positioning.

```typst
#rule-grid(width: 10cm, height: 3cm, spacing: 20pt)
#place(
  dx: 180pt,
  dy: 40pt,
  rect(fill: white, stroke: red, width: 1in, "This will originate at (180pt, 40pt)")
)
#v(3cm)
```

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

### Display Current Margin Note Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note-defaults.md

Imports the necessary module and displays the current stroke, fill, and side settings for margin notes. Ensure the 'drafting' package is imported and page properties are set.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#context {
  let defaults = margin-note-defaults.get()
  [Current stroke: #repr(defaults.stroke)]
  [Current fill: #repr(defaults.fill)]
  [Current side: #repr(defaults.side)]
}
```

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

### Using Alternative Drawing Functions with set-margin-note-defaults

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-margin-note-defaults.md

Integrates a custom drawing function (`sticky-rect`) with `set-margin-note-defaults` to render margin notes as stylized sticky notes. Imports `stickybox` from the `colorful-boxes` preview.

```typst
#import "@preview/colorful-boxes:1.1.0": stickybox

#let sticky-rect(stroke: none, fill: none, width: 0pt, content) = {
  stickybox(rotation: 30deg, width: width/1.5)[
    #set text(0.9em)
    #content
  ]
}

#set-margin-note-defaults(rect: sticky-rect, stroke: none, side: right)
#margin-note(dy: -5em)[Why not use sticky notes in the margin?]
```

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

### Column Layout with set-page-properties

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-page-properties.md

Shows that `set-page-properties` functions correctly within a multi-column page layout.

```typst
#set page(margin: 2cm, columns: 2)
#set-page-properties()

#lorem(50)
#margin-note[Works with multi-column layouts]
#lorem(50)
```

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

### Basic Margin Lines Usage

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-lines.md

Demonstrates the basic usage of the margin-lines function to render default gray lines in the margins. Ensure the 'drafting' package is imported and page margins are set.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#margin-lines()
#lorem(100)
```

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

### Check Current Margin Note Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/errors.md

Inspect the current default settings for margin notes. This is useful for verifying your configuration and understanding available options.

```typst
#context {
  let defaults = margin-note-defaults.get()
  [Page width: #defaults.page-width]
  [Left margin: #defaults.margin-left]
  [Right margin: #defaults.margin-right]
}
```

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

### Basic Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Demonstrates how to place simple and styled notes in the left or right page margin, including offset notes.

```typst
#margin-note[Simple note]
#margin-note(stroke: blue, side: left)[Styled note on left]
#margin-note(dy: 1em)[Offset note]
```

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

### Assigning Reviewers to Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Create distinct margin note functions for different reviewers by using `.with()` to pre-configure styles like stroke color.

```typst
#let reviewer-a = margin-note.with(stroke: blue)
#let reviewer-b = margin-note.with(stroke: purple)
#lorem(10)
#reviewer-a[Comment from reviewer A]
#lorem(5)
#reviewer-b(side: left)[Reviewer B comment]
#lorem(10)
```

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

### Save and Restore Margin Note Defaults

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note-defaults.md

Demonstrates how to temporarily change margin note defaults (stroke and fill) and then restore them using a saved configuration. This is useful for localized styling.

```typst
#context {
  let saved-defaults = margin-note-defaults.get()
  
  // Make temporary changes
  set-margin-note-defaults(stroke: blue, fill: blue.lighten(80%))
  #margin-note[Blue note]
  
  // Restore using saved dictionary
  set-margin-note-defaults(
    stroke: saved-defaults.stroke,
    fill: saved-defaults.fill
  )
  #margin-note[Back to default style]
}
```

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

### Visualize Margin Rectangles for Testing

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Use `place-margin-rects()` to visualize the margin areas on the page. This helps in testing and ensuring that notes fit properly within the defined margins.

```typst
#set-page-properties()
#place-margin-rects(fill: gray.lighten(80%), opacity: 30%)
// Check if notes fit properly
```

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

### Update Margin Note Defaults

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note-defaults.md

Use `set-margin-note-defaults` for recommended state updates. Direct modification using `.update()` is possible but not advised.

```typst
// Not recommended:
#margin-note-defaults.update(old => old + (stroke: blue))

// Recommended:
#set-margin-note-defaults(stroke: blue)
```

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

### Optional Global Note Customization

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Configures global defaults for margin notes, including line color, background, side, visibility, and link style.

```typst
#set-margin-note-defaults(
  stroke: blue,           // Line color
  fill: white,            // Background color
  side: right,            // left or right
  hidden: false,          // Show or hide
  link: "line",           // "line" or "index"
)
```

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

### Assigning Different Reviewers to Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note.md

Shows how to create distinct margin note styles for different reviewers by aliasing `margin-note.with` and applying unique strokes.

```typst
#let reviewer-a = margin-note.with(stroke: blue)
#let reviewer-b = margin-note.with(stroke: red)
#reviewer-a[Review comment from A]
#reviewer-b[Review comment from B]
```

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

### Troubleshooting: RTL Layout

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Ensures correct note placement for Right-to-Left languages by setting the text language before calling `set-page-properties()`.

```typst
#set text(lang: "ar")  // Arabic
#set page(margin: 2cm)
#set-page-properties()  // Auto-detects RTL
```

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

### Print-Friendly Configuration (Hidden Notes)

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Configure margin notes to be hidden by default, suitable for printing the document without the notes displayed. This uses `hidden: true` in the defaults.

```typst
#set page(margin: 2.5cm)
#set-page-properties()
#set-margin-note-defaults(hidden: true)

// All notes are hidden, document ready for printing
```

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

### Professional Document Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Set up a professional document style with specific margin, stroke, fill, and side properties for margin notes. This configuration uses black strokes and white fill.

```typst
#set page(margin: 2.5cm)
#set-page-properties()
#set-margin-note-defaults(
  stroke: (paint: black, thickness: 0.5pt),
  fill: white,
  side: right,
  hidden: false,
)
```

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

### Book-Style Layout with Auto Margins

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Sets up book-style page margins (inside/outside) and configures drafting, allowing notes to automatically adjust their placement.

```typst
#set page(margin: (inside: 2.5cm, outside: 2cm))
#set-page-properties()

// Notes automatically adjust for inside/outside margins
#margin-note[Margin note]
```

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

### Academic/Textbook Style Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Set up an academic or textbook style with specific left and right margins, and custom numbering for margin notes and outlines. This configuration uses yellow fill for notes.

```typst
#set page(margin: (left: 3cm, right: 2cm))
#set-page-properties()
#set-margin-note-defaults(
  link: "index",
  stroke: black,
  fill: yellow.lighten(70%),
  inline-numbering: i => [*#i*],
  note-numbering: i => [*Note #i:* ],
)
#note-outline(title: "Annotations", level: 1)
```

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

### Batch Similar Notes for Consistent Styling

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Group margin notes of the same style together by setting defaults before creating multiple notes. This ensures consistent styling for batches of similar notes.

```typst
#set-margin-note-defaults(stroke: blue)
#margin-note[Note 1]
#margin-note[Note 2]
#margin-note[Note 3]

#set-margin-note-defaults(stroke: red)
#margin-note[Different style note]
```

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

### Transparent Margin Visualization

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-place-margin-rects.md

Visualize margin areas with a specific fill color and opacity, or set padding to 0% for a tight visualization. This helps in precise layout checks.

```typst
#place-margin-rects(
  fill: red,
  opacity: 20%,
  padding: 0%
)
#lorem(100)
```

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

### Review/Draft Document Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Configure margin notes for a review or draft document, using blue styling and enabling link to an index. The `side` is set to `auto` for dynamic placement.

```typst
#set page(margin: 2cm)
#set-page-properties()
#set-margin-note-defaults(
  stroke: blue,
  fill: blue.lighten(90%),
  link: "index",
  side: auto,
)
#margin-note[Editor note]
#margin-note[Review comment]
#note-outline(title: "Review Comments")
```

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

### Custom Rectangle Style for Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note.md

Demonstrates how to define and apply a custom rectangle style for margin notes using `rect.with`. This allows for consistent styling across multiple notes.

```typst
#let custom-rect = rect.with(radius: 0.5em, fill: yellow.lighten(70%))
#set-margin-note-defaults(rect: custom-rect)
#margin-note[Note using custom rect style]
```

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

### Enable Debug Mode Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Conditionally applies styles for debugging. Use when development builds require visual aids.

```typst
#let DEBUG = true

#set page(margin: 2cm)
#set-page-properties()

#if DEBUG {
  place-margin-rects(fill: gray.lighten(80%), opacity: 50%)
  set-margin-note-defaults(stroke: red, fill: red.lighten(80%))
} else {
  set-margin-note-defaults(stroke: black, fill: none)
}
```

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

### note-outline

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/INDEX.md

Generates an index of all notes, including margin and inline notes, with visual indicators.

```APIDOC
## note-outline

### Description
Generates an index of all notes with clickable links and visual color indicators.

### Parameters
- **title** (string) - Optional - The title for the outline.
- **level** (integer) - Optional - The indentation level for notes.
- **row-gutter** (length) - Optional - Spacing between rows.

### Returns
- **content** - A formatted list with clickable links to notes.
```

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

### Narrow Page Layout for Print

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-page-properties.md

Configures `set-page-properties` for a narrow page size, demonstrating automatic margin calculation for non-standard dimensions.

```typst
#set page(width: 15cm, height: 21cm, margin: 1.5cm)
#set-page-properties()

#margin-note[Margins automatically calculated for narrow page]
```

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

### Troubleshooting: Margins Too Narrow

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/quick-start.md

Provides solutions for notes not fitting in margins by increasing page margins or reducing note element size, like `caret-height`.

```typst
#set page(margin: (left: 3cm, right: 3cm))  // Wider margins
#set-margin-note-defaults(caret-height: 0.5em)  // Shorter connecting line
```

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

### Visualizing Multiple Margin Types

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-place-margin-rects.md

Demonstrates visualizing margin rectangles for both standard uniform margins and book-style (inside/outside) margins. Use `pagebreak()` to separate sections.

```typst
// Standard margins
#set page(margin: 2cm)
#set-page-properties()
#place-margin-rects(fill: blue.lighten(80%))
#lorem(30)

#pagebreak()

// Book-style margins
#set page(margin: (inside: 2.5cm, outside: 2cm))
#set-page-properties()
#place-margin-rects(fill: green.lighten(80%))
#lorem(30)
```

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

### Asymmetric Grid for Complex Layouts

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-rule-grid.md

Creates an asymmetric grid with different horizontal and vertical spacing, and dotted gray lines. Suitable for complex, non-uniform layouts.

```typst
#rule-grid(
  width: 20cm,
  height: 15cm,
  spacing: (1cm, 0.5cm),  // 1cm horizontal, 0.5cm vertical
  stroke: (paint: gray, dash: "dotted")
)
#v(15cm)
```

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

### Check Current Margin Note Settings

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Retrieves and displays the current settings for margin notes. Useful for debugging or verifying configuration.

```typst
#context {
  let defaults = margin-note-defaults.get()
  
  if defaults.page-width == none {
    [Warning: page-width not set!]
  } else {
    [Page width: #defaults.page-width]
  }
}
```

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

### Basic Margin Note Usage

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-margin-note.md

Demonstrates the fundamental usage of the margin-note function to add a simple note to the margin. Ensure the 'drafting' package is imported and page margins are set.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#lorem(20)
#margin-note[This is a comment in the margin]
#lorem(20)
```

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

### Array Type Usage for Spacing and Divisions

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/types.md

Illustrates how to use arrays to define spacing and divisions for grid layouts. The array elements correspond to x and y axes respectively.

```typst
#rule-grid(spacing: (10pt, 5pt))    // 10pt x-spacing, 5pt y-spacing
#rule-grid(divisions: (10, 5))       // 10 x-divisions, 5 y-divisions
```

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

### Index-Based Numbering for Margin Notes

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-margin-note-defaults.md

Configures margin notes to use index-based numbering for linking and display. Includes a call to `note-outline()` to visualize the notes.

```typst
#set-margin-note-defaults(link: "index")
#margin-note[First note]
#margin-note[Second note]
#note-outline()
```

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

### Import Drafting Package

Source: https://github.com/ntjess/typst-drafting/blob/main/README.md

Import the drafting package from the official Typst preview namespace. Ensure you use the correct version.

```typst
#import "@preview/drafting:0.2.2"
```

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

### Basic Absolute Placement

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-absolute-place.md

Use this to place an element at a specific offset from the top-left corner of the page. Ensure sufficient vertical space is created to make the positioned content visible.

```typst
#import "@preview/drafting:0.2.2": *

#absolute-place(dx: 5cm, dy: 3cm, rect(width: 2cm, height: 1cm, "Positioned"))

#v(10cm) // Create space so content is visible
```

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

### Margin Note: Missing Margin Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/errors.md

This error indicates that `margin-note` was called without the necessary margin configuration. Either use `set-page-properties()` or explicitly define all required defaults.

```typst
#set page(width: 21cm, height: 29.7cm)
// Missing margins!
#margin-note[Error]
```

```typst
#set page(margin: 2cm)
#set-page-properties()
#margin-note[OK]
```

```typst
#set-margin-note-defaults(
  margin-left: 2cm,
  margin-right: 2cm,
  page-width: 17cm,
)
#margin-note[OK]
```

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

### Basic Style Change with set-margin-note-defaults

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/api-reference-set-margin-note-defaults.md

Demonstrates changing the default stroke color of margin notes from red to blue. Imports the drafting library and sets up basic page margins.

```typst
#import "@preview/drafting:0.2.2": *
#set page(margin: 2cm)
#set-page-properties()

#lorem(10)
#margin-note[Default style with red stroke]
#lorem(10)

#set-margin-note-defaults(stroke: blue)
#margin-note[Now blue stroke applies]
#lorem(10)
```

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

### Multiple Reviewer Configuration

Source: https://github.com/ntjess/typst-drafting/blob/main/_autodocs/configuration.md

Define distinct margin note styles for multiple reviewers using `margin-note.with()`. This allows each reviewer's comments to have a unique visual identifier.

```typst
#let reviewer-alice = margin-note.with(stroke: blue)
#let reviewer-bob = margin-note.with(stroke: red)
#let reviewer-charlie = margin-note.with(stroke: green)

#reviewer-alice[Alice's comment]
#reviewer-bob[Bob's comment]
#reviewer-charlie[Charlie's comment]
```