Skip to content

Typst

Background

Markdown

In Computer Society/Skynet we sue Markdown a lot (this page is written using markdown).
Markdown works fine for most things, its human readable and can be rendered to HTML.
You can (sometimes) embed html tags in it as well, although those are inconsistent across implementations.
Different implementations cannot agree with each other either.

LaTeX

For more complex documents (such as our constitution) we have used LaTeX.
LaTeX is currently 42 years old and while powerful it also has cruft.
While there is documentation it is harder to get to.
Overleaf the newer online editing platform is helping somewhat but even then it can be a lot to learn.

One other quirk is that to get teh correct table of contents (ToC) on teh constitution ye had to run the command 3 times. This was to:

  1. Generate the bulk of the document
  2. Generate a placeholder ToC
    • This had the effect of shifting all other pages down one or two pages
  3. Regenerate it again with the correct ToC

Typst

Ideally we want something that is a nice middle ground.
Thankfully Typst is exactly that.

  • Simpler syntax than LaTeX
  • Can format it better than Markdown
  • This includes converting to PDF's which is what we (Compsoc) mostly want
  • The tooling itself is FOSS

Usage

Installing

Any repo which uses Typst will have it in its devshell (nix develop).
This will allow ye to use typst compile or typst watch on any Typst file.

IDE

In Jetbrains there is a (free) plugin called Kvasir which adds real time preview for Typst files.
It does not require typst to be installed to function.

Converting files

To convert files you need to run this command: 

# this will compile and output teh file in the same directory as the source file
typst compile --root . path/to/typst/file.typ

# This will do the same as compile but it will watch for changes
typst watch --root . path/to/typst/file.typ

Format

Markdown

Typst is pretty similar to Markdown

Item Markdown Typst
Header H1 # Text = Text
Header H2 ## Text == Text
List item (ordered) 1. Item + Item
List item (unordered) * Item - Item
Bold **text** *text*
Italic *text*/_text_ _text_
Newline, same paragraph space + space + newline \ + newline
Link <https://skynet.ie> https://skynet.ie
Link (pretty) [Skynet](https://skynet.ie) #link("https://skynet.ie")[Skynet]

You can find the full list of shorthand's here: documentation

LaTeX

For the three (3) people who know how to use LaTeX typst have a guide to tide ye over:
LaTeX Guide

Scripting

One nice thing about Typst is that while ye can use the basic formatting ye can also extend it with functions.
An example would be this reference function.
It looks up the label and sees what the number of teh headings is, for example 4.2.5 and outputs it as text, very useful if ye want to refer to another area in teh body of text.
Prior to this each reference would have to be updated manually.