Noteworks

The Noteworthy framework as a Typst package: modular educational documents with structured chapters, themed content blocks (definitions, theorems, examples, problems), and 2D/3D plotting built on CeTZ.

A Noteworks project is a single file — main.typ holds the configuration, the structure, and (if you like) the pages themselves. As your notes grow, split pages out into one file per page and #include them:

my-notes/
├── main.typ      # your book: configuration + structure
└── content/      # optional: one file per page

Usage

Scaffold a project (Typst downloads the package automatically):

typst init @preview/noteworks:0.3.0 my-notes
cd my-notes
typst compile main.typ

The scaffolded project is the demo book — 12 chapters that double as the module reference, all in one main.typ. Strip it down and make it yours.

Local development

To test unpublished changes, link this repo into your local preview package cache — Typst prefers it over the registry download:

# macOS data dir; use ~/.local/share/typst/packages on Linux
mkdir -p ~/Library/Application\ Support/typst/packages/preview/noteworks
ln -s /path/to/this/repo ~/Library/Application\ Support/typst/packages/preview/noteworks/0.3.0

Authoring

main.typ configures the document and declares the whole book:

#import "@preview/noteworks:0.3.0": *

#show: noteworthy.with(
  title: "My Notes",
  subtitle: "An Example",
  authors: ("Me",),
  affiliation: "My School",
  theme: "aether", // 15 built-in schemes
)

#cover()
#preface[Welcome to my notes.]
#toc()

#chapter("My First Chapter", summary: "What this chapter covers.")
#page("Some Page")[
  #definition("Inline")[Page bodies can live right here...]
]
#page("Another Page")[#include "content/0/2.typ"]

Chapter and page numbers — and the table of contents — follow document order automatically: insert, remove, or reorder entries and everything renumbers on the next compile. Leave out #cover(), #preface[..], or #toc() if you don't want them. Every noteworthy option has a default; pass only what you change (fonts, numbering padding, block design, solution visibility, ...).

If you split pages into separate files, start each file with the same import:

#import "@preview/noteworks:0.3.0": *

That single import provides the themed blocks (definition, theorem, example, note, proof, solution, ...) and the qualified modules (canvas, graph, shape, data, combi, dsa, trees, timeline).

Labels and references

Give a block a label: and name it with @ from anywhere in the book:

#theorem("Pythagoras", label: "pythagoras")[ $a^2 + b^2 = c^2$ ]

By @pythagoras, the hypotenuse is the longest side.

The reference reads as the block's heading does ("Theorem 3"), in the block's colour, and links to it; from another page it adds where to look ("Theorem 3 in Chapter 02.01"). Pass number-blocks: true to noteworthy to number blocks, block-numbering: "chapter" or "document" to make the number carry more of its address, and ref-format: "number-only" to drop the page from references. A solution counts within the block it is in, and a labelled one reads "Solution 2 of Example 1". A label nobody defined shows as ?name in red rather than failing the compile.

Drawing

shape builds geometry -- points, segments, lines, circles, arcs, angles, polygons, polyline for an open path, brace for measuring a span, and text-at for putting any content at a coordinate -- and a canvas draws it: canvas.cartesian-canvas, polar-canvas, trig-canvas in the plane, space-canvas in three dimensions. arc and angle take either points or angles; points may be (x, y) or (x, y, z) tuples anywhere.

space-canvas has a camera (azimuth, elevation, projection: "perspective"), sorts everything it draws by depth, and takes every flat shape as well as 3D points, vectors, graph.parametric curves that return three numbers, and graph.surface -- a parametric surface drawn as shaded facets. The scaffolded demo book shows each of these.

Examples

examples/ contains a small calculus notes book built with the template. Because it lives inside this repo, it imports the package entrypoint relatively (#import "../lib.typ": *) instead of @preview/noteworks:x.y.z — it compiles from a fresh clone with no installation and never needs a version bump:

typst compile --root . examples/main.typ examples/calculus.pdf

(Scaffolded projects can't do this — typst init copies only the template files, so they import the package by name.)

Notes

• The package exports page, toc, and outline, which shadow the Typst builtins for wildcard importers — use std.page / std.outline in content files if you need the builtins.
• Plotting uses @preview/cetz and @preview/cetz-plot; Typst downloads them automatically on first compile.
• Default fonts are IBM Plex Serif and Noto Sans Adlam; install them or pass font: / title-font: to the noteworthy show rule.

License

MIT — see LICENSE.