Typst is Weird and I Really Like It

For reasons not entirely understood to humankind, some software developers have an aversion to WYSIWYG: Typing into Microsoft Word¹ and immediately seeing what the document looks like seems strangely alien. In some cases, this is warranted: If you write a 300-page thesis, modern desktop software is not able to cope with it, while being perfectly able to play back 4K video that is being streamed live from some remote data centre.

As every self-respecting nerd in their adolescence, I experimented with LaTeX, a typesetting system that generates documents from plain-text input: it’s this promised land of perfect typography which has an aura of a scientific mindset. But to be honest, the whole thing is something for frizzy, grey-haired hippies: The syntax is horrifying, the tooling is byzantine, and adding a character that is not in the English alphabet can lead to a total meltdown.² Also, the typographical output is not as good as many people claim it to be.

For publishing on the web, Markdown came into dominance. And it’s not bad if your name is John Gruber and you never need to author a table. I do not want to be too harsh on Markdown; this post has been composed in it!

But it gets tricky when you write a “document”: be it a manual, tech documentation, an invoice or similar. You want a table of contents? Variables that you can reference? Insert a formula? Tough luck, you will be scripting.

Asciidoc has an acceptable syntax and promises more features, but it’s often unclear what is part of the language and what is part of one of the implementations. Tables of contents, for example, are handled very differently depending on whether you use Asciidoctor for generating an HTML file or Asciidoctor-PDF for creating a PDF. Especially the latter often feels half-baked.

I need to generate PDF documents from structured data on a regular basis, so I cobbled together a workflow consisting of YAML files for data input, a Jinja template that produces HTML, and then a little bit of Python code that combines those two and feeds it to WeasyPrint, which generates a PDF file. It works, but I don’t really love it.

A while ago, I stumbled upon Typst, which looked to me like an online editor for scientific writing but is, in fact, a typesetting system. It has a reasonable markup language, generates PDFs, is fast, and doesn’t litter your file system with intermediate files.

It allows a lot of scripting inside the markup, which makes it a perfect match for data-driven documents.

name: Jon Doe
sandwiches:
  - Chicken Teriyaki
  - Philly Cheese Steak
  - Salami

and

#let data = yaml(sys.inputs.path)

= Sandwich Documentation

Hi #data.name! Our records indicate that your favourite
sandwiches are
#data.sandwiches.join(", ", last: " and ").

glued together with a

typst w doc.typ --input "path=sandwich.yaml"

gives you a PDF document that looks something like this:

And while normal text looks very reasonable if you are used to the usual markup languages, you can use all sorts of tricks to generate a specific output. You have a number that you want to display as currency? Try this:

#let as_currency(value, round: true) = {
  let v = value
  if round {
    v = calc.round(decimal(value), digits: 2)
  }

  let s = data.currency + "\u{00A0}" + str(v)
  if s.ends-with(regex("\.\d")) {
    s += "0"
  } else if not s.ends-with(regex("\.\d*")) {
    s += ".00"
  }
  s
}

If you spend too much time in Typst, your document may look more like a program than text sprinkled with markup, but that’s maybe what you wanted and what you’re most familiar with. A kind of strangeness that’s beautiful – and fun.