typst-authoring

# Typst Authoring Reference

Typst is a modern typesetting language with three syntactic modes: **markup** (default), **code** (`#`), and **math** (`$`). Understanding mode transitions is the core skill for productive authoring.

## Three Modes at a Glance

- **Markup mode** (default) — Text, `*bold*`, `_italic_`, `= Heading`, `- list`, `+ ordered`, `/ term: def`
- **Code mode** (enter with `#`) — Variables, functions, control flow, imports. End with `;` to return to markup.
- **Math mode** (enter with `$`) — `$inline$` (no spaces) or `$ block $` (spaces). Single letters = italic variables; multi-letter = function names.

## Essential Syntax Quick Reference

| Element            | Syntax                                  |
| ------------------ | --------------------------------------- |
| Bold / Italic      | `*bold*` / `_italic_`                   |
| Heading            | `= H1`, `== H2`, `=== H3`               |
| Lists              | `- bullet`, `+ numbered`, `/ Term: def` |
| Link               | `https://...` or `#link("url")[text]`   |
| Label / Reference  | `<name>` / `@name`                      |
| Code expression    | `#expr`                                 |
| Line break         | `\`                                     |
| Comment            | `// line` or `/* block */`              |
| Non-breaking space | `~`                                     |
| Dashes             | `--` (en), `---` (em)                   |
| Escape             | `\#`, `\@`, `\$`, `\*`, etc.            |

## Set Rules and Show Rules

**Set rules** configure defaults for functions:

```typst
#set text(font: "New Computer Modern", size: 11pt)
#set par(justify: true)
#set heading(numbering: "1.")
#set page("a4", margin: (x: 2.5cm, y: 2.5cm))
```

Set rules are scoped to their enclosing content block `[...]`.

**Show rules** transform rendering:

```typst
#show heading: set text(navy)              // show-set (composable)
#show heading: it => emph(it.body)         // transformational
#show: columns.with(2)                     // everything rule
#show heading.where(level: 1): set align(center)  // filtered
```

Selectors: element functions, `.where(field: val)`, `"text"`, `regex(...)`, `<label>`, or bare `show:` for everything.

Prefer show-set rules over transformational rules for composability.

## Page Layout Essentials

```typst
#set page("a4", margin: (x: 2.5cm, y: 2.5cm), numbering: "1")
#set page(header: [Title #h(1fr) Author], footer: context [
  #h(1fr) #counter(page).display("1/1", both: true)
])
#set page(columns: 2)          // page-level columns (preferred)
#colbreak()                    // manual column break
#pagebreak(weak: true)         // page break
```

When a custom `footer` is set, the `numbering` parameter is silently ignored — display page numbers manually via `counter(page).display()`.

## Code Mode Essentials

Enter with `#`. Key types: `none`, `auto`, `bool`, `int`, `float`, `str`, `content`, `array`, `dictionary`, `length`, `ratio`, `fraction`, `function`.

Single-element array: `(1,)` (trailing comma required). Empty dict: `(:)`.

```typst
#let x = 42
#if x > 10 [big] else [small]
#for item in items [#item, ]
#let greet(name, excited: false) = [Hello #name#if excited [!]]
```

Functions are pure. Use `.with()` for partial application. Import with `#import "file.typ": item` or `#import "@preview/pkg:version": item`.

## Math Mode Essentials

```typst
$a^2 + b^2 = c^2$                    // inline
$ sum_(i=0)^n a_i = integral f(x) dif x $  // block

$ frac(a, b), sqrt(x), root(3, x) $  // fractions, roots
$ mat(1, 2; 3, 4) $                   // matrix (semicolons = rows)
$ vec(a, b, c) $                      // vector
$ cases(1 "if" x > 0, 0 "else") $    // cases
```

Greek: `alpha`, `beta`, `gamma`, `pi`, etc. Blackboard bold: `NN`, `ZZ`, `RR`, `CC`. Accents: `hat(x)`, `dot(x)`, `tilde(x)`, `arrow(x)`. Styles: `bold(A)`, `cal(A)`, `bb(N)`, `frak(P)`.

Equation numbering: `#set math.equation(numbering: "(1)")`. Reference with `$ ... $ <label>` and `@label`.

## Tables Quick Reference

```typst
#table(
  columns: (1fr, auto, auto),
  table.header([*Name*], [*Age*], [*City*]),
  [Alice], [30], [NYC],
  [Bob], [25], [LA],
)
```

Key features: `table.cell(colspan: 2)`, `table.cell(rowspan: 3)`, `table.hline()`, `table.vline()`. Alignment/fill/stroke accept arrays (cycle per column) or `(x, y) =>` functions. Use `table` for data (accessible), `grid` for layout.

## Figures and Bibliography

```typst
#figure(image("photo.jpg", width: 80%), caption: [A photo.]) <fig>
@fig shows the photo.

#bibliography("refs.bib", style: "ieee")
@key, @key[p.~7], #cite(<key>, form: "prose")
#footnote[Note text]
```

## Key Gotchas

1. **Fraction parens consumed:** `(a+b)/c` removes the parens. Double them: `((a+b))/c`.
2. **`context` required for introspection:** `counter.get()`, `state.get()`, `query()`, `measure()`, `here()`.
3. **Counter starts at zero:** Step before display. `step()`/`update()` return content that must be placed.
4. **Custom footer kills numbering:** Set `footer:` means `numbering:` is ignored.
5. **Show rules bypass defaults:** Transformational show rules lose numbering, spacing, block behavior.
6. **Math multi-letter:** `area` in math = function name. Use `"area"` for text.
7. **`#` in math:** Access code variables with `#`: `$ #x < 17 $`.

## Additional Resources

### Reference Files

For detailed syntax, patterns, and examples, consult:

- **`references/markup-and-layout.md`** — Full markup syntax table, headings, lists, labels, references, escaping, page setup, margins, headers/footers, columns, spacing, alignment, block/box
- **`references/scripting.md`** — Code mode, types, let bindings, destructuring, control flow, functions, closures, argument sinks, operators, methods, imports, modules
- **`references/math.md`** — Math mode, symbols, Greek letters, subscripts/superscripts, fractions, roots, matrices, vectors, alignment, equation numbering, delimiters, cases, accents, font styles, custom operators
- **`references/tables-figures-bibliography.md`** — Tables (columns, headers, cell spans, alignment, fill, stroke, grid vs table), figures, images, captions, floating figures, bibliography, citations, footnotes
- **`references/advanced.md`** — Custom functions, templates, counters, state, query, context keyword, numbering patterns, metadata, measure, packages
- **`references/visualizations.md`** — Visualization packages: diagrams (fletcher, CeTZ, diagraph, pintorita), charts (lilaq), timelines (timeliney), callout boxes (gentle-clues). Design principles for reader-friendly documents

### Typst Document Template

Standard document setup for reports and research output:

```typst
#set page(margin: (x: 2.5cm, y: 2.5cm), numbering: "1")
#set text(font: "New Computer Modern", size: 11pt)
#set par(justify: true, leading: 0.65em)
#set heading(numbering: "1.1")
#show link: it => text(fill: rgb("#2563eb"), it)
```

### Special Character Escaping in Typst Content

Characters requiring `\` escape in content text: `#`, `@`, `$`, `<`, `>`. When converting Markdown to Typst, escape these in body text but not inside code blocks.

### Markdown-to-Typst Conversion

| Markdown      | Typst                               |
| ------------- | ----------------------------------- |
| `# Heading`   | `= Heading`                         |
| `**bold**`    | `*bold*`                            |
| `*italic*`    | `_italic_`                          |
| `1. item`     | `+ item`                            |
| `[text](url)` | `#link("url")[text]`                |
| `> quote`     | `#blockquote[text]` (custom helper) |
| `[1]` refs    | `#super[1]`                         |