blog/content/software/typst.md

Title	Date	Lang	Author	Category	Tags	Slug	table-of-contents	Summary	Header_Cover
Typesetting with Typst	2024-10-19 18:00	en	Fabrice	software	vim, neovim, typst	typst-intro	true	Simple typesetting with Typst.	../images/covers/printing-press.jpg

For about ten years now, I’ve been using LaTeX to typeset any document which aims to be printed. The main reason is that I’m quite familiar with the syntax to adjust the page setting to what I imagine. Other solutions exist to ease this workflow, such as Pandoc to convert easier to write syntax to other formats. However, this solution was not palatable to me as the universal aspect of Pandoc, makes it a pain to specify pagination properties. And, to produce a PDF in the end, Pandoc calls LaTeX, and for the sake of simplicity I prefer to directly write in LaTeX (see the conclusion for clarification).

However, for some kind of documents that I don’t write very often, such as letters, it’s sometimes a pain to find the syntax of the LaTeX class for letters^(fr) I use. Recently, I had to write small documents (approx 3 pages), with a bibliography, and that just needed to have a nice and neat presentation. Before going farther, I decided to give a try to typst. It is an open-source typesetting engine that is written in rust, that promotes modern features such as incremental compilation, and a scripting language that is actually readable by humans. Moreover, the markup language is clean, and as in markdown or asciidoc, it can be read from the source (without a concealer) to have an idea of the typeset text before compiling it.

The project is still in development and some features may break before the first major version is out. However, to quickly generate a document, it can be a good idea to consider. It is also to note that there is no native output from Typst to html, but Pandoc can read and write .typ files, so it’s an alternative worth considering given that native LaTeX is not easy to write for that purpose.

In the following, it will be a quick overview of the features that I find nice in Typst. Please don’t expect a in-depth review, I only used it for a couple of opportunities.

Example: a letter (the French way)

Now, let us look at what a Typst document looks like. For a simple example, I’ll take the letter one, for which I wrote a simple template to generate them. The template is available in this repository. The main issue I had is that the French way of doing letters revert the order of the addresses of the sender and recipient are… reverted compared to the English style.

Let us dig in what it does by looking at the example file.

First thing first, the file is loading the template from lettre.typ. This file defines the typesetting and the paginations properties, and provide a initialisation function to define the different headers, which you can look into if you feel curious. If you find it a bit unbearable, you can create a new file preamble.typ to hide everything, and include it with #include "preamble.typ" at the outset of the file.

#import "lettre.typ": *
#show link: strong

#show: doc => lettre(
  de: [
    Sender\
    Address
  ],
  pour: [
    Recipient\
    Address
  ],
  objet: "subject of the letter", // optional
  date: "date of sending", // optional
  lieu: "location",
  introduction: "opening",
  cloture: "closing",
  signature: "signature",
  post: [
    post-letter (e.g., post-scriptum)
  ],
  doc
)

This will generate the template with the elements where they should be, in a very simple fashion. Now, we just have to write the content of the letter and have a pdf file pretty easily with typst compile without all the files that LaTeX generates for us. As a bonus, it also set some PDFs metadata from the input variables.

Bibliography

Another nice feature is that Typst embeds a bibliography engine, that is compatible with the bibtex format. Meaning that I don’t have to change the way I manage my bibliography or directly use community-managed bibliography

For that you simply have to call the bibliography function where you want it to be generated:

#bibliography("bibliography.bib", title: "References", style: "springer-basic")

And cite the references you want with the @bibkey syntax (note that it’s the same syntax for cross-referencing) or the #cite function. Note that if you have a + in your bibliography key, the label won’t be recognized. It is my case as my bibkeys are in the alpha style with the initials of the authors + year up to 3 names, and a + afterward… To be able to cite the reference anyway, just do #cite(label("bib+key")).

The full list of natively available style is given in the Typst documentation, however you can define your own in the Citation Style Language. Meaning that you can pick the best one for your usage in the CSL repository.

Note that the bibliography command does not seem to be recognized

Tooling

Unlike my blogpost about using nvim for LaTeX, it’s pretty much easier here.

I just added the typst.vim plugin to neovim, added a binding for the :TypstWatch command and that’s basically all. It is possible to set the g:typst_pdf_viewer (vim.g.typst_pdf_viewer in Lua) global variable as well if you want to have a different default PDF viewer for your system and for edition.

Now, each time I save, the document is incrementally compiled (I think) and updated in my PDF viewer.

I tried using typst language servers as well, but they don’t seem mature yet and in the end the typst.vim plugin suffices to my needs without being too nosy.

Hopefully, the tooling will be better with time.

Conclusion

For simple document typesetting, even with features such as bibliography, cross-referencing, and table of contents, Typst seems to be a good choice. However, for long-term support documents, such as documentation, I would wait to see it being more stable. Even while writing this blog post, the lettre template I made was done in Typst 0.11, and preparing it in a repository raises some warnings about breaking changes from 0.12:

Added par.spacing property for configuring paragraph spacing. This should now be used instead of show par: set block(spacing: ..) (Breaking change)

Which let me also say that one other advantage from Typst is… the error messages that are way much cleaner than the ones from LaTeX. Leading to easier debugging as well. I, however, can’t say for sure as I didn’t typeset big documents using Typst yet (which is unlikely to happen given my stance so far, but who knows…).

Finally, to complete the note about compiling in latex from Pandoc in the introduction of this blogpost… I’m apparently not up to date. For the sake of transparency, it is possible to use different PDF engines with Pandoc according to the documentation. I didn’t try them yet, so I can’t provide feedbacks about them. Note that Typst is part of the PDF generators, as well as other nice typesetting projects such as pagedjs that aims at paginating HTML sources to have great web page and print-ready PDFs. However, the argument about avoiding intermediate steps if possible still holds (moreover when the syntax of Typst is already clean enough).

See Also

• Awesome Typst: a repository listing useful links for typst users.
• Typst for LaTeX users: a comprehensive guide for typst for LaTeX users.