A new Typst Handbook aimed at people coming new to Typst has been made available by Stephano Rama. It therefore assumes zero knowledge or coding experience, but the explanations and examples could well be helpful to those with more experience of coding.
I have downloaded it, but haven’t yet had time to go into it. What I do know is that I wish it had been available when I started exploring Typst 18 months ago, but still expect to learn a lot from it, as the online Typst documentation can be opaque to those like me.
Bonus for Italian speakers… it was originally written in Italian (available from the same Github repo).
Thanks for posting this. It finally got me to sit down for a few hours and give Typst a good try.
Obviously it does all the basic stuff in a much “cleaner” way than LaTeX – that’s the benefit of decades of user testing – but I’m very impressed with the in-built programming language. I’ve used TeX/LaTeX for decades, and every time I have to code something I enter a world of pain. Typst, though, again benefits from decades of software tooling development, and makes this relatively straightforward and very approachable – I laughed at its support of closures and recursion.
The only thing that confused me was the “show” rules, though I think that’s just a naming problem – perhaps transform instead? – or a misunderstanding on my part.
Anyway, the proof is in the eating, as they say, so I plan to port something over and see where I get to – down a rabbit hole, no doubt, especially tikz => cetz.
Yes, TikZ > CetZ is what held me back (from switching to Typst) these past two years.
My main workflow uses Quarto for computational programming reasons (to execute Python and R code), and Quarto natively supports both LaTeX and Typst. With regard to TikZ specifically, it is possible within a Quarto document to compile to PDF using Typst, yet have a LaTeX/TikZ figure within the document that will get processed separately. Basically, Quarto will use pdflatex or xelatex etc. to compile that LaTeX/TikZ block separately, generate the vector or raster image and save it temporarily, then re-insert the image in the proper location when Typst compiles the document.
All this to say, I think I can start to play around more with Typst while preserving “critical” TikZ figures in the textbook that I am working on.
I do find Typst templates to be confusing, and I hope this new handbook elucidates that for me!
Do bear in mind that the handbook was written with the absolute beginner in programmatic typesetting in mind, not people with (years of) experience with LateX/quarto/Pandoc. So even for me, with 18 months of stumbling around with fair success in Typst itself, the first few chapters come across as somewhat patronising.
But I think the later chapters, and the examples at the end will help me sort out things I’m still struggling with. Two things struck me above:
@auxbuss says, “The only thing that confused me was the “show” rules, though I think that’s just a naming problem – perhaps transform instead? – or a misunderstanding on my part.”
@cavalierex says, “I do find Typst templates to be confusing, and I hope this new handbook elucidates that for me!"
I hope it does help. To an extent, that reminds me of those coming new to Scrivener from Word (or learning a first foreign language or a language like Thai or Chinese, Japanese, Korean or Arabic)… prior knowledge and expectations of how things work get in the way. I didn’t have that problem with Typst, but it did take me a while to get templating to work… I was using #include instead of #import, a difference the Handbook explains clearly.
Also, even though @nontroppo says combining Typst with Pandoc and Quarto makes things easy (easier), for me, who really have no need of Typst but am just keeping my ageing brain active by extending what I was already doing with Scrivener + NWP to produce more beautiful output, combining them was more confusing and just working directly in Typst is much easier. But then I have no figures and diagrams in TikZ that I need to recreate in CetZ to get into a Typst document.
Oh, and the other thing I know I will find helpful is that Stephano Rama has included the complete Typst code of both the Italian and English versions in the GitHub repository.
Hi all! Stefano here, the author of the handbook. Thank you for the warm reception, and Mark especially for bringing it to this community.
A few quick replies:
@auxbuss you’re not misunderstanding anything: “transform” is exactly the right mental model for show rules, and that’s actually how the handbook frames them, a show rule intercepts an element and transforms it into something else. The name is just a bit of Typst history; once you read “show” as “transform”, it clicks. (And yes, closures and recursion in a typesetting language are a joy.)
@cavalierex templates confused me at first too. The short version: a template is just a function that wraps your whole document and applies your set/show rules in one place. You load it with #import "@preview/...": * and apply it with #show: template.with(...). The handbook builds one from scratch in the styling and project chapters, I hope that part helps.
And Mark is right that the first chapters are deliberately gentle (they assume zero programming) (Maybe a little too much? Maybe. But that’s how I saw it.), so experienced users should feel free to skip ahead, the later chapters and the ready-to-use templates at the end are probably where you’ll get the most value.
The full source of both versions (Italian and English) is on GitHub (LINK), and I’m fixing things as readers report them, so if anything is unclear, please tell me. (main_IT is the main .typ file in Italian, and (…guess what?) main_EN is the main .typ file in English. There are also two PDF files included (which can be distinguished by the _IT/_EN .pdf suffix at the end of the filename).
