# Edu vocabulary

> Every function and template in @typstream/edu (@typstream/edu:0.1.0), with its signature, parameters and a live example.

Source: https://typstream.vercel.app/docs/reference/edu/vocabulary

{/* Generated by apps/website/scripts/generate.mjs from @typstream/edu's eduCatalogue. Don't edit: edit the `///` comments in packages/edu/typst/. */}

This page is generated from the doc comments in `@typstream/edu`'s Typst sources: the same text the
[prompt kit](/docs/guides/prompting) gives the model, so the two can't drift apart. Each example below is
compiled live in your browser; tick **Show answers** to see the teacher's copy.

Documents get every name below through the plugin's preamble (`#import "@typstream/edu:0.1.0": *`), so they
call `#question(…)` directly. See [@typstream/edu](/docs/reference/edu) for setup.

## Templates

Applied to the whole document with `#show: name.with(…)`.

### `worksheet`

```typst
worksheet(title: none, subject: none, grade: none, info: ("name", "date", "class"), instructions: none, lang: auto, paper: "a4", points-label: auto, body)
```

A worksheet: title, subject and grade, and lines for the student's name, date and class.
Apply it as the document's first line.

- title (content, str, none): The worksheet's title.
- subject (content, str, none): E.g. "Mathematics".
- grade (content, str, none): E.g. "Grade 5".
- info (array, dictionary, none): Student fields (see `student-info`): names for empty lines, `("name", "date")`, or a dictionary to fill some in, `(name: [Ikram], date: none)`; `none` for none.
- instructions (content, none): Instructions shown under the title.
- lang (str, auto): The document's language, e.g. "ar" or "bn"; sets the text language for the whole document, title included.
- paper (str): Paper size, e.g. "a4" or "us-letter".
- points-label (str, function, auto): Word for points, e.g. "marks"; `auto` is "points" in the document's language.

```typst
#show: worksheet.with(title: [Adding Fractions], subject: [Mathematics], grade: [Grade 5])
```

### `quiz`

```typst
quiz(title: none, subject: none, grade: none, info: ("name", "date", "class"), instructions: none, lang: auto, paper: "a4", points-label: auto, body)
```

A quiz: like a worksheet, with the total of the questions' points under the title.

```typst
#show: quiz.with(title: [The Solar System], subject: [Science], grade: [Grade 4])
```

### `exam`

```typst
exam(title: none, subject: none, grade: none, duration: none, info: ("name", "class", "roll"), instructions: none, lang: auto, paper: "a4", points-label: auto, body)
```

An exam: title, subject, duration and total points, student fields, an instructions box, and
from page 2 a running header with the title and a candidate box.

- duration (content, str, none): E.g. [2 hours].

```typst
#show: exam.with(
  title: [Algebra I Final Examination],
  subject: [Mathematics],
  duration: [2 hours],
  instructions: [Answer *all* questions. Show your working.],
)
```

### `lesson-plan`

```typst
lesson-plan(title: none, subject: none, grade: none, duration: none, date: none, teacher: none, lang: auto, paper: "a4", body)
```

A lesson plan for the teacher: title and a table of subject, grade, duration, date and teacher.
Write objectives with `learning-objectives` and the stages as headings.

```typst
#show: lesson-plan.with(title: [The Water Cycle], subject: [Science], grade: [Grade 6], duration: [45 minutes])
```

### `handout`

```typst
handout(title: none, subtitle: none, subject: none, grade: none, teacher: none, lang: auto, paper: "a4", body)
```

A handout or notes for students: title, subtitle, and a line with the subject, grade and teacher.

```typst
#show: handout.with(title: [Photosynthesis], subtitle: [Key ideas], subject: [Biology])
```

## Questions

Numbered through the document; each keeps its points for the totals.

### `question`

```typst
question(points: none, body)
```

A numbered question. Numbers run through the whole document; points, when given, appear at
the end of the line and count towards the template's total. Put the question's answer space
(`blank`, `answer-lines`, `mcq`, …) inside it. Sub-parts are a numbered list (`+ …`), lettered
`(a)`, `(b)`, ….

- points (int, none): Points the question is worth.

```typst
#question(points: 2)[
  What is $3/4$ of 20?
  #answer-space(height: 3em, answer: [15])
]
```

### `mcq`

```typst
mcq(..options, answer: none, columns: auto)
```

Multiple-choice options, lettered (a), (b), … in the document's language. Give each option as
its own content argument, in brackets, math too: `[$x = 3$]`. `answer` is the correct option's
number, counting from 1, or an array of numbers when several are correct.

- answer (int, array, none): The correct option(s), 1-based.
- columns (int, auto): Options per row. `auto` fits short options on one or two rows.

```typst
#question(points: 1)[
  Which planet is closest to the Sun?
  #mcq([Venus], [Mercury], [Mars], [Earth], answer: 2)
]
#question(points: 1)[
  Solve $x^2 = 9$.
  #mcq([$x = 3$], [$x = 3$ or $x = -3$], [$x = 9$], answer: 2)
]
```

### `true-false`

```typst
true-false(answer: none, body)
```

A statement to mark true or false.

- answer (bool, none): Whether the statement is true.

```typst
#true-false(answer: false)[The Sun orbits the Earth.]
```

### `matching`

```typst
matching(..pairs)
```

Two columns to match: give the correct pairs, each as `(left, right)`. The right column is
shuffled (the same way every time) and the key is worked out from the pairs, so write them
in their natural order, correctly matched.

```typst
#matching(
  ([perro], [dog]),
  ([gato], [cat]),
  ([pájaro], [bird]),
)
```

## Answer spaces

Where students write. Each takes an `answer` that only the teacher's copy shows.

### `blank`

```typst
blank(width: 4em, answer: none)
```

An inline blank to fill in, e.g. in a sentence or after an equals sign. When answers are shown,
the answer is written on it.

- width (length): Width of the line. It grows to fit a shown answer.
- answer (content, none): The expected answer.

```typst
Water boils at #blank(answer: [100]) °C at sea level.
```

### `answer-lines`

```typst
answer-lines(count: 3, spacing: 2em, answer: none)
```

Ruled lines for a written answer of a sentence or more, across the full width.

- count (int): Number of lines.
- spacing (length): Distance between lines.
- answer (content, none): A model answer, written on the lines when answers are shown.

```typst
Explain why the Moon has phases.
#answer-lines(count: 3, answer: [We see different parts of its sunlit half as it orbits Earth.])
```

### `answer-space`

```typst
answer-space(height: 4em, boxed: false, answer: none)
```

Empty space for working, a drawing or a calculation.

- height (length): Height of the space. It grows to fit a shown answer.
- boxed (bool): Draw a frame around the space.
- answer (content, none): A worked answer, written in the space when answers are shown.

```typst
Solve $3x + 4 = 19$. Show your working.
#answer-space(height: 5em, answer: [$3x = 15$, so $x = 5$.])
```

## Answers

Hidden unless `sys.inputs.showAnswers` is `"true"`.

### `answer`

```typst
answer(body)
```

A worked solution or explanation, shown only when answers are shown. Use it for anything a
teacher's copy should add: full solutions, marking notes, expected points.

```typst
#answer[The ratio is $3 : 4$ because both sides divide by 5.]
```

### `answer-key`

```typst
answer-key(title: auto)
```

The answers to every question, by question number, for a key at the end of the document.
Like every answer it appears only when answers are shown, so it is safe in a student's copy.

- title (content, auto): Heading of the key. `auto` is "Answer key" in the document's language.

```typst
#answer-key()
```

## Teaching content

Boxes, lists and tables around the questions.

### `callout`

```typst
callout(kind: "note", title: auto, body)
```

A highlighted box for a note, tip, warning, definition, worked example or something to
remember. Its title defaults to the kind's name in the document's language.

- kind (str): One of "note", "tip", "warning", "definition", "example", "remember".
- title (content, auto, none): The box's title.

```typst
#callout(kind: "definition")[A *prime number* has exactly two factors: 1 and itself.]
```

### `instructions`

```typst
instructions(body)
```

Instructions for students, in a framed box titled "Instructions" in the document's language.

```typst
#instructions[
  - Answer *all* questions.
  - Show your working.
]
```

### `learning-objectives`

```typst
learning-objectives(body)
```

What students will learn, as a titled box. Write the objectives as a list.

```typst
#learning-objectives[
  - Describe the stages of the water cycle.
  - Explain how the Sun drives evaporation.
]
```

### `rubric`

```typst
rubric(..criteria, levels: auto, points: auto)
```

A grading rubric: one row per criterion, one column per level. Give each criterion as
`(name, description for the first level, the next level, …)`.

- levels (array, auto): Level names, best first. `auto`: four levels named in the document's language.
- points (array, auto, none): Points per level. `auto` counts down to 1; `none` hides them.

```typst
#rubric(
  ([Thesis], [Clear and arguable.], [Clear.], [Vague.], [Missing.]),
  ([Evidence], [Strong, cited.], [Relevant.], [Thin.], [None.]),
)
```

### `student-info`

```typst
student-info(..fields)
```

Lines for students to write their name, the date, their class, and so on, or those details
filled in. Known fields are "name", "date", "class", "section", "roll", "score" and "teacher",
labelled in the document's language; any other text is its own label, as written (capitalise
it, in the document's language). A plain field is an empty line; one given as `key: value` has
its value written on the line, and `none` leaves it empty. A label of your own with a value goes
in a dictionary, `("Year": [2026])`, as a template's `info` is. The name field gets the most room.

```typst
#student-info("name", "class", "roll")
#student-info(name: [Ikram Hasan], class: [9B], date: none, ("Year": [2026]))
```

## Drawings

Native Typst shapes; inline SVG with an `aria-label` in HTML.

### `number-line`

```typst
number-line(from: 0, to: 10, step: 1, length: 12cm, labels: auto, points: (), open-points: (), marks: ())
```

A number line with ticks every `step`, numbered, with arrows at both ends. Mark answers or
examples with filled `points` and hollow `open-points` (as in inequalities), and name values
with `marks`.

- from (int, float): Leftmost value.
- to (int, float): Rightmost value.
- step (int, float): Distance between ticks.
- length (length): Length of the line.
- labels (auto, none, array): Which ticks are numbered. `auto` numbers every tick (every 5th or
  10th on long lines); `none` numbers none, for students to fill in; an array lists values,
  or `(value, label)` pairs such as `(0.5, $1/2$)`.
- points (array): Values marked with a filled dot.
- open-points (array): Values marked with a hollow dot.
- marks (array): `(value, label)` pairs written above the line.

```typst
#number-line(from: -5, to: 5, points: (2,), open-points: (-1,), marks: ((2, [A]),))
```

### `graph-paper`

```typst
graph-paper(cols: 30, rows: 10, step: 5mm, major: 5)
```

Squared paper for drawing graphs, shapes or bar charts, with a darker line every `major` squares.

- cols (int): Squares across.
- rows (int): Squares down.
- step (length): Side of a square.
- major (int, none): Darker line every this many squares; `none` for none.

```typst
#graph-paper(cols: 20, rows: 8)
```

### `coordinate-plane`

```typst
coordinate-plane(x: (-5, 5), y: (-5, 5), unit: 7mm, grid: true, labels: true, points: ())
```

A coordinate plane on a square grid, with numbered x and y axes. Plot `points` as `(x, y)` or
`(x, y, label)`.

- x (array): The x range, `(min, max)`.
- y (array): The y range, `(min, max)`.
- unit (length): Size of one unit.
- grid (bool): Draw grid lines.
- labels (bool): Number the axes.
- points (array): Points to plot.

```typst
#coordinate-plane(x: (-4, 4), y: (-3, 3), points: ((1, 2, [A]), (-3, -1, [B])))
```

## Chemistry

An mhchem-like subset written as math, so HTML gets MathML.

### `ce`

```typst
ce(formula)
```

A chemical formula or equation from plain text: digits after an element are subscripts, a
leading number is a coefficient, `^2+` or a trailing `+`/`-` is a charge, `(aq)`, `(s)`,
`(l)`, `(g)` are states, `*` is a hydrate's dot, and `->`, `<=>`, `<-` are arrows. Separate
species, `+` and arrows with spaces. Works in text and in math.

```typst
#ce("2H2 + O2 -> 2H2O") and #ce("CH3COOH <=> CH3COO- + H+"); copper sulfate is #ce("CuSO4*5H2O").
```

## Templates as `template` names

Apps that ask the model for a body only can apply a template themselves: `<Typstream template="quiz">` (or
`mountTypstream`'s `template` option) looks the name up in the plugins' `templates`. A document that writes its own
`#show: quiz.with(…)` must not get one too: it would apply twice.

| Name | Title | What it adds |
| --- | --- | --- |
| `worksheet` | Worksheet | Title, subject and grade, and name, date and class lines. |
| `quiz` | Quiz | A worksheet with the total of the questions' points. |
| `exam` | Exam | Duration and total points, student fields, an instructions box and a running header. |
| `lesson-plan` | Lesson plan | A table of subject, grade, duration, date and teacher; no student fields. |
| `handout` | Handout | Title and subtitle, with no student fields. |
