Get started with the Typst programming language for documents

Typst is an easy and powerful markup-based language for creating technical documentation and books – and a compelling alternative to TeX and LaTeX. When we think of documents, or documentation, they tend to fall into two circles. First are business documents, typically composed with an office application like Microsoft Word or Google Docs. Second is project documentation, often created semi-automatically from a project using an app like Sphinx or Pandoc. But there’s a third circle, one that can overlap the other two. These are documents produced by a typesetting language—a combination of markup and programming language used to produce books, textbooks, academic journals, scientific papers, technical manuals, and other documents where the formatting and layout is crucial. A typesetting language allows you to create a handy, human-readable document that serves both as a single source of truth and as a foundation for outputting to print, web, e-book, and other formats. Over the last few years, an open-source project has shaped up to be a powerful choice for meeting all of those needs: Typst (pronounced “typist”). TeX, LaTex, and now Typst For decades, the preeminent typesetting language was TeX, better known in its more recent incarnation LaTeX. TeX was originally created by Donald Knuth in 1978, and LaTex followed in 1984. TeX and LaTeX have broad adoption and they’re almost universally supported and understood. But they have two big, long-standing problems. The first is they’re old. They were created for an entirely different world of computing, and their age shows in cumbersome syntax and management. The second is the general complexity of using their language. In fact, LaTex was originally created as a way to make using TeX less complicated, but the underlying complexity of TeX was impossible to hide. Typst was created as a clean-slate solution to the problems and limitations of TeX and LaTeX. It shares many of the same ideas. For instance, Typst lets you typeset mathematical formulas using a syntax similar to the syntax used to express mathematical formulas in a programming language. But it does not try to be compatible with TeX syntax (although you can use third-party tools to convert TeX formulas to Typst.) Typst CLI, web app, and VS Code extension Typst is available as a standalone command-line program (the open-source Typst compiler), as a hosted web playground (the Typst app, shown below), or as an add-on for Visual Studio Code (Tinymist Typst being the most popular). The web playground gives you the fastest possible hands-on experience: all you need to do is start typing, and you’ll see a live preview. (The Tinymist add-on for VS Code also displays previews.) The web playground for Typst. All content is previewed live as you type. The current export mode, PDF, preserves positioning and formatting exactly. Foundry For most basic documents, Typst doesn’t require much extra syntax. You can just type Markdown-flavored text, and have that formatted as you’d expect. Underscores and asterisks can be used for emphasis or bold; section heads can be set with equals signs at the start of a line; and so on. Typst’s programming capabilities come into the picture when you want to start modifying the document’s presentation beyond its defaults. For instance, if you wanted to set the page size, margins, fonts, and paragraph formatting, you’d use declarations like these: #set page(width:5.25in, height:8in, margin: .5in) #set text(size: 11pt, font: "Libre Baskerville") #set par(first-line-indent: 1.75em,justify: true) #set commands make changes from that point forward in the document. If you place these at the top of your document, they affect everything below it. But you could use other #set commands later to override those changes — for instance, if you switch from one text column to two. Typst code mode The hash (#) in Typst (except when escaped with a slash) is used to signal a switch from regular text (markup mode) to Typst commands (code mode). Those commands can span multiple lines, until the Typst code block or expression is concluded: This is regular text. #let inline_image(img) = { box(height: 8em, place(top+left, dx: 5pt, square( image(img, height:100%, fit:"cover") ))) } This is regular text again. Here, we’ve used #let to define a function that takes one argument (the name of an image), and inserted it into an inline box. The curly braces indicate the body of the function, but individual lines end in a line break as in Python, not in a semicolon as in JavaScript. Typst exports to various formats — PDF, images, and HTML — although it’s optimized for the static layouts of PDF and images. Some kinds of formatting don’t render by default in HTML mode, if only because Typst can’t make reliable guarantees about how to do that (e.g., page headers and footers, which don’t really exist in HTML). What you can do is determine what the current export target is, via the target() function, and take action based on that: #let sectionbreak(txt) = { context( if target()=="html" { html.elem("div", attrs:(class:"section-break"))[] return } else { divider() }) } In this example, we’re creating a sectionbreak() function that has two behaviors. For HTML targets, it inserts an empty div tag with a CSS class that we could style with a style sheet. For all other targets, it defaults to the built-in divider() function. All of the document’s attributes are available in Typst code. The query function uses a syntax similar to JavaScript’s element querying system: query( heading.where( level: 1, ) ) This would return all document headings at level 1, then let you iterate over them, manipulate their contents, perform other introspection, and so on. Typst also has its own package manager and package directory. Packages do not need to be formally installed from the directory; you can simply reference them in your Typst program with an import statement, and they’ll be included. Typst math mode Typst’s math blocks are patterned after TeX, but aren’t a drop-in replacement for TeX. That said, anyone with a little programming experience should be able to pick up how Typst’s math mode works. Math formulas are set aside from text by dollar signs: $ sum_(k=1)^n k = (n(n+1)) / 2 $ This block renders to the equation shown in the above screenshot. As with the hash, the dollar sign can be escaped with a slash if you need it in text. If you have a great deal of existing material composed in TeX, you can use a third-party tool to translate that TeX to Typst. The MiTex package can perform this inline for individual formulas or entire TeX documents. Automating Typst The Typst language and ecosystem are still relatively new, and the language has limitations. Some are just a matter of features needing further development. Others, like the strict limitations on paths for imports or reading data, are by design. One way to get around limitations in Typst is to wrap it in another programming language. Python is an easy choice, and the typst Python library provides a high-level way to drive the Typst compiler. This lets you orchestrate complex workflows with multiple files, read data outside of the project root, or perform Typst queries to read document data. In time, some of what you might need to shim up this way may become native features. The community around Typst is already quite active (over a thousand packages are available for it), and new releases come regularly.