typstream
@typstream/edu

@typstream/edu

The Typst vocabulary for teachers' documents (templates, questions, answers and keys, callouts, rubrics, drawings, chemistry) as a typstream plugin with a prompt kit.

@typstream/edu is the vocabulary typstream teaches the model for teachers' documents: worksheets, quizzes, exams, lesson plans and handouts. It is a Typst package (functions such as #question, #mcq and #blank, and templates) plus the CSS for its HTML, packaged as a TypstreamPlugin, with a prompt catalogue generated from the package's doc comments. Every function has a page in the vocabulary.

When to use it

Use it when your app writes educational documents. The plugin gives documents the functions without an #import, the prompt kit tells the model how to use them, and answers stay out of the student's copy. If your documents are something else, leave it out: typstream renders plain Typst on its own, and you can write your own plugin the same way (see Writing a plugin).

Install

npm install @typstream/edu

Example

import { edu } from "@typstream/edu";
import { Typstream } from "typstream";

<Typstream plugins={[edu]} source={text} isStreaming={isStreaming} />;
// A teacher's copy: the same document with answers shown, recompiled, not re-prompted.
<Typstream plugins={[edu]} source={text} inputs={{ showAnswers: "true" }} />;

The plugin mounts the package's files (eduFiles) and adds a preamble (eduPreamble) that imports every public name, so documents call #question and friends directly. Its stylesheet (eduCss) is added to the HTML renderer for you. The model writes a document like this one (tick Show answers to see the teacher's copy):

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

#question(points: 2)[$1/2 + 1/4 =$ #blank(answer: $3/4$)]
#question(points: 1)[
  Which is largest?
  #mcq([$1/2$], [$2/3$], [$3/5$], answer: 2)
]
#question(points: 2)[
  Explain how you compare fractions.
  #answer-lines(count: 2, answer: [Rewrite them with a common denominator.])
]
#callout(kind: "tip")[Find a common denominator first.]
#answer-key()

Edu documents builds a complete worksheet app around it.

Vocabulary

Every function works in the paged and the HTML target. The vocabulary has each one's signature, parameters and a live example.

KindFunctions
Templates (#show: name.with(…))worksheet, quiz (adds the total points), exam (duration, total, instructions box, running header), lesson-plan (details table), handout
Questionsquestion (numbered through the document), mcq, true-false, matching (give the correct pairs; edu shuffles the right column and works out the key)
Answer spacesblank, answer-lines, answer-space
Answersanswer (worked solutions), answer-key
Teaching contentcallout (note, tip, warning, definition, example, remember), instructions, learning-objectives, rubric, student-info
Drawingsnumber-line, graph-paper, coordinate-plane (native shapes; inline SVG with an aria-label in HTML)
Chemistryce: #ce("2H2 + O2 -> 2H2O"), an mhchem-like subset (subscripts, coefficients, charges, states, hydrates, arrows) written as math, so HTML gets MathML

Answers

Answers are part of the document: answer: on blank, mcq, true-false, answer-lines and answer-space, #answer[…] for worked solutions, and #answer-key() to list them all. They appear only when the input showAnswers (SHOW_ANSWERS_INPUT) is "true": written in place in red, the correct option in bold, and listed by answer-key() under their question numbers. Otherwise they produce no output in either target, so a student's copy can't leak them. The answer key itself appears only in the teacher's copy.

To switch copies, set the input and recompile. The model isn't asked again:

<Typstream plugins={[edu]} source={text} inputs={{ [SHOW_ANSWERS_INPUT]: showAnswers ? "true" : "false" }} />

Streaming

edu is written for text that arrives a few characters at a time. Every parameter has a default, and arguments cut mid-stream are accepted: (2 heals to the number 2, and 5em arrives as 5 first. A half-written call renders instead of failing the compile.

Languages

Labels, option letters, the points word and callout titles come in English, Arabic and Bengali, picked by the document's language. Pass lang: "ar" or lang: "bn" to the template. In Arabic, edu's HTML gets dir="rtl". The Arabic and Bengali wording is a first draft that still needs review by native speakers. See Fonts and languages for the script fonts.

#show: quiz.with(title: [الكسور], lang: "ar")

Using it with plain Typst

The package needs no typstream. In typstream it is a local package: the plugin mounts its files under @typstream/edu:0.1.0/… (EDU_ROOT), which the engine roots at that package, so nothing is fetched and it needs no package allowlist entry. With the typst CLI, put its typst/ directory where Typst looks for that package, import it the same way, and pass --package-path:

mkdir -p packages/typstream/edu
cp -r node_modules/@typstream/edu/typst packages/typstream/edu/0.1.0
typst compile --package-path packages --input showAnswers=true main.typ
main.typ
#import "@typstream/edu:0.1.0": *
#show: worksheet.with(title: [Adding Fractions])

On the server, pass eduPreamble and eduFiles to @typstream/node:

import { eduFiles, eduPreamble } from "@typstream/edu";
import { render } from "@typstream/node";

const pdf = await render(source, "pdf", { preamble: eduPreamble, files: eduFiles, inputs: { showAnswers: "true" } });

API

ExportWhat it is
eduThe plugin: files, preamble, templates, prompt kit and stylesheet.
eduCssStyles for the HTML edu's functions write.
eduFilesThe package's Typst sources, keyed by their engine path.
eduPreambleTypst that imports every public name.
EDU_ROOT, EDU_VERSION"@typstream/edu:0.1.0" and "0.1.0".
SHOW_ANSWERS_INPUT"showAnswers".
eduTemplatesThe templates as TemplateSpecs, for the template option.
eduCatalogueOne entry per public function and template, from the doc comments.
eduExamplesWhole documents for few-shot prompts.
eduPromptRulesHow to write documents with edu, for the system prompt.
buildSystemPrompt (beta)The system prompt for the plugins' vocabulary.
typstPromptRules (beta)Typst habits models get wrong whatever the vocabulary.

edu

const edu: TypstreamPlugin;

edu as a typstream plugin, with key "edu" and version EDU_VERSION. Its facets:

FacetValue
engine.fileseduFiles
engine.preambleeduPreamble
templateseduTemplates
prompt{ catalogue: eduCatalogue, rules: eduPromptRules, examples: eduExamples }
stylesheets[eduCss]

Pass it in plugins to <Typstream>, mountTypstream or engine.open, and to buildSystemPrompt. See Plugins.

eduCss

const eduCss: string;

Styles for the HTML edu's functions write. Rules are scoped to the renderer's root (class typstream) with zero specificity, so your own rules win, and they follow the renderer's theme variables, so dark mode works. Without them the HTML keeps its content and structure but loses answer lines and boxes. The plugin's stylesheets facet carries it, so the HTML renderer and standalone HTML exports include it; you only need it directly when you render edu's HTML yourself.

eduFiles

const eduFiles: Readonly<Record<string, string>>;

edu's Typst sources and typst.toml, keyed by their path in the engine under EDU_ROOT ("@typstream/edu:0.1.0/lib.typ" and so on). Mount them as a document's files.

eduPreamble

const eduPreamble: string; // '#import "@typstream/edu:0.1.0": *\n'

Typst to put before a document: imports every public function and template.

EDU_ROOT and EDU_VERSION

const EDU_ROOT = "@typstream/edu:0.1.0";
const EDU_VERSION = "0.1.0";

EDU_ROOT is the package spec edu's files are mounted under. The engine roots paths of the form @ns/name:x.y.z/path at that package, so #import "@typstream/edu:0.1.0" reads the mounted files. EDU_VERSION is the package's version, as in its typst.toml.

SHOW_ANSWERS_INPUT

const SHOW_ANSWERS_INPUT = "showAnswers";

The input that shows answers: set it to "true" and recompile for a teacher's copy. See Answers.

eduTemplates

const eduTemplates: TemplateSpec[];

The five templates by name (worksheet, quiz, exam, lesson-plan, handout), each with a title, a description and a preamble (#show: worksheet). They are for apps that let the teacher pick the document type and ask the model for the body only: <Typstream template="quiz">, or mountTypstream's template option.

A document that applies its own template (#show: worksheet.with(…), what the prompt kit asks for by default) must not also get one of these: the template would apply twice.

Prop

Type

eduCatalogue

const eduCatalogue: FunctionDoc[];

One entry per public function and template (23 of them), generated from the /// doc comments in the package's Typst sources, so it can't drift from the functions. buildSystemPrompt puts it in the prompt, and the vocabulary page is generated from it.

Prop

Type

eduExamples

const eduExamples: PromptExample[];

Whole documents in edu's vocabulary, for few-shot prompts: a chemistry exam, an Arabic quiz, a Bengali worksheet and a fractions worksheet.

Prop

Type

eduPromptRules

const eduPromptRules: string[];

How to write documents with edu, for the system prompt: start with one template line, never import edu, wrap numbered questions in #question, give every answer to edu rather than as plain text, use #blank instead of underscores, and so on. They come from measuring real models with and without them, and each one targets an error class those runs produced. Every edu function they call exists and takes the arguments they name.

buildSystemPrompt

Beta

buildSystemPrompt, SystemPromptOptions and typstPromptRules are @beta: their output and shape may change between releases.

const buildSystemPrompt: (plugins: readonly TypstreamPlugin[], options?: SystemPromptOptions) => string;

Writes the system prompt for documents in the plugins' vocabulary: an introduction, typstPromptRules, then each plugin's rules and function catalogue, then their example documents. It is deterministic for the same plugins, so the prompt caches. Any plugin with a prompt facet contributes, for example @typstream/universe's list of packages the model may import.

import { buildSystemPrompt, edu } from "@typstream/edu";
import { universe } from "@typstream/universe";

const system = buildSystemPrompt([edu, universe]); // about 19,000 characters, ~8.4K tokens
const short = buildSystemPrompt([edu, universe], { examples: false });

Prompting covers how to use it with your model.

Prop

Type

typstPromptRules

const typstPromptRules: string[];

Beta. Typst habits models get wrong whatever the vocabulary: Markdown syntax, a code fence around the reply, scripts without a base in math (m/s$^2$), multi-letter names in math, bare math as a function argument, and characters that need escaping. buildSystemPrompt puts them first; pass typstRules to replace them.

See also

On this page