Typst, simple markup language for documentation

[Picuino]

Not long ago, I came across an alternative to LaTeX and Markdown + Pandoc for generating technical and other types of documentation.

My problem was that I wanted to find a markup language for generating PDF documentation that was both simple and powerful and automatizable.

LaTeX is very powerful, but it requires countless modules and has a fairly complex syntax that’s difficult to automate.

On the other hand, Markdown with Pandoc seemed simple to me, but it lacked options. It was too simple.

I’ve finally found a very interesting project that’s been around for just a few years (2023) but has already garnered a huge number of stars on GitHub. It strikes a good balance by being quite powerful—even featuring its own language for automating projects—while still being simple to learn.

Furthermore, markup languages today have the advantage of receiving invaluable assistance from AI, which understands them quite well.

I've already started transcribing documents I had in Writer (Word) into Typst markup format. So far, I've run into some issues trying to add a vertical line between two columns of text. The project is still in version 0.15, so there are still some details that need to be ironed out.

On the other hand, the compiler takes up barely 50 MB and is extremely fast. It’s nothing like LaTeX. It’s also much more powerful and customizable than Markdown.

I definitely have a new tool for generating PDF documentation now.

https://en.wikipedia.org/wiki/Typst
https://typst.app/docs/tutorial/writing-in-typst/
https://github.com/typst/typst
 
Edit: characteristics

- Open Source (Apache License 2.0)
- Free offline compiler + Free online services + Premium online services (like Git and GitHub)
- With scripting language
- Offline tool: https://github.com/typst/typst/releases/
- Online service: https://typst.app/play/

[Picuino]

Example:

Code: [Select]

#set page(
  paper: "a6",
  margin: (x: 1.8cm, y: 1.5cm),
)
#set text(
  font: "New Computer Modern",
  size: 10pt
)
#set par(
  justify: true,
  leading: 0.52em,
)

= Introduction
In this report, we will explore the
various factors that influence fluid
dynamics in glaciers and how they
contribute to the formation and
behaviour of these natural structures.

Glacier displacement is influenced by a
number of factors, including

+ The climate
+ The topography
+ The geology

This report will present a physical
model of glacier displacement and
dynamics, and will explore the
influence of these factors on the
movement of large bodies of ice.

#align(center + bottom)[
  #image("glacier.jpg", width: 70%)

  *Glaciers form an important
  part of the earth's climate
  system.*
]


[Picuino]

Defining formulas is simple and looks great.

Sorry for the Spanish comments.

Code: [Select]

#set page(
  paper: "a4",
  margin: (top: 2cm, bottom: 1.5cm, left: 2cm, right: 2cm,),
)

#set text(
  font: "Liberation Sans",
  size: 12pt,
  lang: "es" 
)

= Fórmulas
Ejemplos de fórmulas renderizadas por Typst.

+ Soluciones a la ecuación de segundo grado $a x^2 + b x + c = 0$ :

  $ x = (-b plus.minus sqrt(b^2 - 4 a c)) / (2a) $


+ Función de densidad de la distribución normal (o campana de Gauss).

  $ f(x) = 1 / (sigma sqrt(2 pi)) e^(- 1/2 ((x - mu) / sigma)^2) $


+ Con mayor tamaño de letra y sin minimizar los símbolos del exponente.

  #text(size: 14pt)[
    #show math.frac: math.display
    $ f(x) = 1 / (sigma sqrt(2 pi)) e^(- 1/2 ((x - mu) / sigma)^2) $
  ]

+ Fracciones varias

  $ 5 / 7 $
 
  $ (x + 1) / (x - 1) $
 
  #text()[
    #show math.frac: math.display
    $ pi = 4 / ( 1 + 1^2 / ( 2 + 3^2 / ( 2 + 5^2 / ( 2 + 7^2 / ( 2 + dots ) ) ) ) ) $
  ]

+ Límites y sumatorios

  #text(size: 14pt)[
    #show math.frac: math.display
    #show math.limits: math.display
    $ A = lim_(n -> infinity) sum_(i=1)^n f(x_i) dot.c Delta x $
  ]

[studiot]

thank you for the further examples.
Nothing wrong with the Spanish.
But how is this an improvement of what already exists ?

[Zucca]

on my list now, thanks for reporting it.

thank you for the further examples.
Nothing wrong with the Spanish.
But how is this an improvement of what already exists ?

Gemini AI says:

Speed and Compilation

    Typst: Features lightning-fast, incremental compilation that renders your document in milliseconds as you type, providing an instant preview experience similar to web development.

    LaTeX: Relies on older engines (like pdfLaTeX or XeLaTeX) that often require multiple compilation passes, making large documents noticeably slower to build.

Syntax and Usability

    Syntax: Typst uses a clean, unified markup and scripting language that feels intuitive. LaTeX relies on an archaic macro expansion system that frequently requires specialized syntax packages just to do basic math styling or layout.

    Error Handling: Typst provides clear, human-readable error messages pointing directly to the problem area. LaTeX errors are notoriously cryptic, often dumping users into raw terminal logs.

Ecosystem and Maturity

    Ecosystem & Support: LaTeX boasts millions of templates and packages for every niche academic requirement. Most journals and conferences natively accept or require LaTeX submissions.

    Adoption: Typst is rapidly growing and features a built-in package manager, but its ecosystem is still small compared to LaTeX, and formal academic publishers rarely accept Typst source files directly yet.

[Picuino]

I've tried using LaTeX several times, and each time I've found it to be a language that's difficult to learn, write, understand, and get to work. In the end, I gave up trying.

This language is much simpler to write, understand, and get to work. I think I'm going to use it quite a bit. I think it's a very useful tool.

[Picuino]

    Typst: Features lightning-fast, incremental compilation that renders your document in milliseconds as you type, providing an instant preview experience similar to web development.

I compile it offline using the executable I downloaded from GitHub. It's very fast, but not quite as fast as the online version.

[Zucca]

The only thing I do not like there is a "Gmbh" company behind it.

The Typst compiler is free, open source software under the permissive Apache-2.0 license. It is all you need to compile Typst markup to PDFs and other files. All markup that compiles in the web app will work with the Typst compiler and vice versa.

Typst Universe forms an ecosystem with 1550+ packages and templates. Each package or template on Universe is licensed under an open license, either an OSI-vetted open source license, CC-BY, CC-BY-SA, or CC0.

The Typst web app is proprietary, commercial software. It ships with features to manage your Typst projects, an integrated environment with instant preview and an editor, and collaboration. The web app uses APIs of the Typst compiler to improve the experience of using Typst. You can license a copy of the Typst web app for self-hosting on your own infrastructure with Typst On-Premises.

so I am worried things could change in the future? maybe?

ohhh seee, they know poeple could be worried about it:

Will Typst remain open-source?

Yes. We are committed to keep the Typst compiler open-source: We believe that you should have certainty that your investment in Typst is not jeopardized by a change in licensing.

There is a healthy open source ecosystem around the Typst compiler. It has 400+ contributors, most of which are not affiliated with Typst GmbH, the company behind Typst.

The separation between open-source and Commercial software at Typst is clear: The compiler is open and the web app is commercial. Their support for the Typst markup language is the same: All markup that compiles in the web app will work with the Typst compiler and vice versa. We commit to not adding proprietary extensions to the Typst language, so that will remain true in the future.

[Analog Kid]

Example:

Code: [Select]

#set page(
  paper: "a6",
  margin: (x: 1.8cm, y: 1.5cm),
)
#set text(
  font: "New Computer Modern",
  size: 10pt
)
#set par(
  justify: true,
  leading: 0.52em,
)

= Introduction
In this report, we will explore the
various factors that influence fluid
dynamics in glaciers and how they
contribute to the formation and
behaviour of these natural structures.

Glacier displacement is influenced by a
number of factors, including

+ The climate
+ The topography
+ The geology

This report will present a physical
model of glacier displacement and
dynamics, and will explore the
influence of these factors on the
movement of large bodies of ice.

#align(center + bottom)[
  #image("glacier.jpg", width: 70%)

  *Glaciers form an important
  part of the earth's climate
  system.*
]


I must say; I like the look of this markup language. Nice and simple and clear.

[Picuino]

It's like Markdown, but it's almost as powerful as LaTeX.

It also features a scripting language, file import capabilities, and advanced data definition... which make it very powerful.

[voltsandjolts]

I've tried using LaTeX several times, and each time I've found it to be a language that's difficult to learn, write, understand, and get to work. In the end, I gave up trying.

I find LaTeX cumbersome, especially as I use it 0.01% of my work time, so I quickly forget the (many) non-obvious things about using it. But once you're over the initial hurdle and have a document style that's fit for your needs, it becomes much much easier. You can then just get on with writing.

I like the simpler Typst markup and appreciate it's open source for now at least. The trouble is that being a commercial venture it will eventually get sold to new owners who will need to monetise it. Promises of current owners will be forgotten. At that point, different compiler tiers will emerge at different price points and feature fragmentation will make for annoying document incompatibilities, IMO.

[Picuino]

For me, that's also its biggest drawback. But I've already downloaded the compiler, and that will always be enough for the documents I create.

[Zucca]

ohhh Neovim 

https://neovim.io/doc/user/filetype/#_typst

https://neovim.io/doc/user/quickfix/#compiler-typst

https://www.dogeystamp.com/typst-notes2/

plus bunch of stuff/repos on Github...

Nice.

[studiot]

I don't have a compiler and very rarely get error messages in my system.

I also think that markup and tex are software half solutions instead of a properly integrated hardware and software solution.

[Zucca]

a properly integrated hardware and software solution.

like this?

[SiliconWizard]

I use LaTeX for more elaborate documents, and otherwise AsciiDoc. Once you figure out how to theme it, AsciiDoc is good enough. I personally don't see a need for something in-between.

[Zucca]

also AsciiDoc is interesting! thanks!

[studiot]

a properly integrated hardware and software solution.

like this?

No idea what that is, I've never heard of it.
But then there are many things, Horatio, that I've never heard of.

I can tell you though it's nothing like I meant.

I did see a laptop with a double screen in the last couple of years that could have the capability I am referring to, but I don't know if it has ever been programmed that way.

[aeg]

Gemini AI says:

Features lightning-fast, incremental compilation that renders your document in milliseconds as you type, providing an instant preview experience similar to web development.

Ah, have web devs finally jettisoned all that Typescript and CSS baloney and gone back to FrontPage?

[SiliconWizard]

also AsciiDoc is interesting! thanks!

It's rather complete. As I mentioned, the one thing people (including myself) often complain about at first, is theming. The default theme for HTML output is ok (although a bit generic), but for PDF output, it's so bland that it's really not good.

You can start here: https://docs.asciidoctor.org/pdf-converter/latest/theme/
And some examples to start: https://gist.github.com/misuo/5b2af22ca78d5d87c522a817a7a8569d

[Picuino]

From Google AI:


Core Differences

Primary Purpose: Typst is built for pixel-perfect typesetting and layout control (a modern alternative to LaTeX). AsciiDoc is built for content semantics and multi-format publishing.

Output Formats: Typst excels at producing high-quality PDFs natively with incremental compilation, with early HTML support. AsciiDoc natively outputs robust HTML, ePub, and DocBook via toolchains like Asciidoctor.

Styling and Layout: Typst uses a human-readable scripting language for custom layouts and complex styling. AsciiDoc relies on CSS and predefined document structures.

Ecosystem and Setup: Typst is fast, lightweight, and easy to install as a single binary. AsciiDoc has a fragmented, older ecosystem that is harder to configure across different processors.

Diagrams and Math: AsciiDoc has strong built-in diagramming support (Mermaid, PlantUML). Typst handles math concisely and supports diagrams via packages and plugins.


Which one should you use?

Use Typst when: You want absolute control over the look of a printed or PDF document, need clean mathematical typesetting, or want an easier alternative to LaTeX.

Use AsciiDoc when: You are writing large multi-file technical manuals, need robust web and ePub outputs, or prioritize content structure over visual design.

[ebastler]

I don't have a compiler and very rarely get error messages in my system.

I might have missed it, but what is "your system"?

[studiot]

I don't have a compiler and very rarely get error messages in my system.

I might have missed it, but what is "your system"?

Some while ago I paid a lot of money for a program called MathType.

I prefer to output to MathML but this forum doesn't appear to support that, but as I can choose lots of output formats I seem to have found one to suit.

I usually suggest Sciweavers or Codecogs for simple formulae.

Most people don't seem to realise what also can be done with simple Charmap.
The first line of my Tex test in the sticky is straight from the keyboard with no special coding.


If you are referring to the double screen laptop that is a different project I never finished.

[Obin]

Just tried it to make some slides, granted not the core focus, but if LaTeX can do it so should Typst
Nested bulletpoint were a pain..
I do like that it integrates nicely in VScode (tinymist extension) with live updates without any major effort.

[John Coloccia]

I use markdown with pandoc, and typst for rendering. Also, plantuml. It's kind of a complete doc system I developed, along with traceability. Mostly run by some fancy makefiles and a custom utility or two.

Anyhow, this is working nicely for us, and is super flexible and easy to use.