itypst: Interactive typst Documents

itypst makes typst code blocks run!

Warning

This project is currently in a prototype state. Proceed at your own risk!

For example, here we use a computer-algebra (sympy) to define a matrix, display it, then display its determinant:

#import "@local/itypst:0.1.0": cell, use-itypst
#show: use-itypst.with(toml("cell-outputs.toml"), default-lang: "python")

= Matrix Determinant
#cell.run(echo: false)
```python
import sympy as sp
A = sp.Matrix(3, 3, [-1, 2, 3, -4, 5, 6, 7, 8, 9])
s = (3 * sp.pi / 5)
```
#cell.errors()

The matrix
$
  upright(A) dot s = underbrace(
    #cell.inline(`A`),
    "Really Cool!"
  ) dot #cell.inline(`s`) = #cell.inline(`A * s`)
$
has the determinant #cell.inline(`(A * s).det()`, echo: true) $approx #cell.inline(`(A * s).det().n()`)$.

Without itypst, there would be no good way to combine the visual presentation of A (the strength of typst), while also making computation aka. taking its determinant easy (the strength of a programming language).

Installation

Warning

The installation is not yet streamlined. This is planned.

There are two components to itypst:

typst Library: Used in your typst document to declare which cells to run, and where to put their outputs.

1. Install the utpm package manager (for managing local typst packages).
2. Clone the itypst Repository: git clone https://git.sofus.io/so-rose/itypst
3. Enter the typst/ subdirectory, then run utpm ws link --no-copy.
4. Now, in any typst document, you can use #import "@local/itypst:...": ....

itypst Binary: Used to generate cell-outputs.toml from any .typ file annotated using the typst library.

1. cargo install --git https://git.sofus.io/so-rose/itypst, or similarly from the cloned repository.

Running

Warning

itypst is not so easy to use right now. This is planned.

For itypst to work, you will need the following commands to be executable on your path:

• typst: To query and compile the document.
• uv: If you're using Python environments, itypst will automatically try to start a kernel using uv.

Create an example typst file, a cell-outputs.toml, and a uv project

touch example.typ
touch cell-outputs.toml
uv init
uv add jupyter  ## Required: Need the 'jupyter kernel" command.
uv add sympy  ## Optional: Libraries

then copy-paste the example above into example.typ and run

itypst run example.typ

to automatically query for Python code cells, execute them, and (re)compile the PDF using the cell outputs.

If you don't want to use Python, start any Jupyter kernel of your choice, then run:

itypst run --jupyter-connection-file <connection-file>.json <file>.typ

Watching

To auto-regenerate the code cells, and the PDF, whenever the file is modified, just run:

itypst watch example.typ

This also supports --jupyter-connection-file.

Development

Examples

The contents of examples/ are used to indicate intended usage.

examples/minimal: Since python is used, a little environment preparation must be done:

• uv sync: Populate the .venv.
• uv run jupyter kernel: Start a jupyter kernel, generating a connection file that can be used by itypst.

Then, follow the instructions above.

Development Tools

• (optional) prek is suggested to make it easy to conform to all project rules, via pre-commits.
• (optional) cocogitto is suggested to ease creating conformant commit messages, conformant changelog entries, and standardized release processing.
• (optional) licensesnip is suggested to make adding correct license headers easy.

Release Process

Releases shall proceed in the following fashion:

1. Execute cog bump --auto (nothing may be staged). This performs a few checks ex. prek on all files and a passing test-suite.
2. Validate that the generated tags, changelog, and bump-commit are appropriate and as expected. If anything is wrong, this is the last chance to revert.
3. Do git push origin main and git push origin --tags.
4. Publish docs, packages, create a Forgejo release TODO. Perhaps a Justfile that validates the GPG signature, builds and publishes the docs to locally defined destination, builds and publishes any packages, and creates a Forgejo release using the changelog and a custom string entry - maybe even publishes a blog post somewhere too, with the custom string entry?