Ovation Ventures Ovation Developer Docs

Tools

Typst

I introduced Roger to Typst, and now he’s all in on using it in the refactor of the Balance Reporting. So here’s a brief guide about what Typst is and why you might want to use it in your workflows.

Typst is a modern replacement for LaTeX. It is available as a free command-line tool, and as a hosted web app (at the link above).

It uses a markup language similar to (though not identical to) Markdown to produce nicely-formatted PDF documents. A typical Typst document might look like this:

#import "@preview/lilaq:0.4.0" as lq

#set page(
  paper: "us-letter",
  margin: (
    left: 0.5in,
    right: 0.5in,
  ),
)

= This is a header

== This is a subhead

Here is some text, which is formatted mostly like *Markdown*, but not
_completely_ like Markdown.

In addition to normal text, Typst has two other modes: “math” mode and “code” mode. “Math” mode is more or less like LaTeX’s math mode, but without the backslashes. Code mode gives you a very lightweight scripting language that’s a little like JavaScript, but not exactly like JavaScript. In “code” mode you can access Typst’s API to specify more advanced formatting features. (The calls to #import and #page() in the example above are using “code” mode to call API methods.)

One powerful feature of Typst is its ability to load data files from a variety of formats, including JSON, CSV and CBOR. You can iterate over the data from these external data files and format them in your document.

For example, if you have a file called devs.json like this:

{
    "rows": [
        {
            "name": "Ben",
            "location": "USA"
        },
        {
            "name": "Carlos",
            "location": "Peru"
        },
        {
            "name": "Manuel",
            "location": "Argentina"
        }
    ]
}

And a typst file like this:

Some of the devs are:

#for row in json("./devs.json").rows [
- #row.name, who is from #row.location.
]

It will produce this:

You can see how this would be very powerful for creating custom reports.

There are many libraries you can use to enhance your reports. Here is a shell script that uses a public API to graph the number of editions of J.R.R. Tolkien’s most published works. It uses the Lilaq library to draw the graph:

#! /bin/zsh

curl 'https://openlibrary.org/search.json?q=the+lord+of+the+rings' > tolkien.json

typst compile - tolkien.png << 'TYPST'
#import "@preview/lilaq:0.4.0" as lq
#set page(
  width: 4in,
  height: 3.5in,
  margin: 0.125in,
)
#{
let data = json("./tolkien.json")
let docs = data
	.docs
	.sorted(key: doc => doc.edition_count)
	.rev()
	.slice(0, count: 5)
let titles = docs
    .map(doc => doc.title)
    .map(rotate.with(-75deg, reflow: true))
    .map(align.with(right))
    .enumerate()
let values = docs.map(doc => doc.edition_count)
let graphLen = values.len()
let colors = range(graphLen).map(i => oklch(50%, 100%, (360deg * i / graphLen)))
lq.diagram(
  width: 3.5in,
  xaxis: (
    ticks: titles,
    subticks: none,
  ),
  lq.bar(
    range(graphLen),
    values,
    fill: colors,
  ),
)
}

TYPST

And this is the result: There are many more features you can explore by reading the documentation and by exploring the Typst Universe of plugins.

You may write your own libraries, and can even use WASM to write plugins, so long as they don’t require access to any external system. For example, you could write your own graphing library in Rust or AssemblyScript using third party graphics libraries so long as they don’t require reading or writing files or accessing the GPU.