Building Websites with Just Typst

Work in progress

This site you’re seeing is built with Typst. Typst is the only build tool required to build the site.

The build command is quite simple: the site has a dist.typ file with a shebang ¹ . I set the execution bit for the file, then execute the file in my command line. I think this is cool.

Before you read, please keep in mind that I don’t have a lot of web development experience. I just graduated from high school and sometimes I am extremely opinionated on certain technologies.

Building a Simple Site Today

Building a site today correctly is… rather complicated. Many sites use at least one web framework or template engine. I’ve used Jinja2, WebC, and Nunjucks, as well as Eleventy and Astro.

I’ve never liked any of them. All of them except Jinja2 require spinning up Node, installing a package manager, and adding a bunch of files such as packages.json and some-manager.lock. I was using those frameworks without understanding how they work most of the times. Sometimes I want a feature to work, so I tried reading the documentation of the framework, but that feature is hidden in multiple layers of documents, so I quit and asked an AI instead – and LLMs don’t give accurate and up-to-date info all the time. In fact, I used LLM multiple times for configuring Tailwind CSS in my site, but it always gave outdated syntax for Tailwind CSS version 3 while I am using version 4.

Typst is a new, complicated language, and LLMs are bad at writing Typst. I’ve been writing Typst for a year, and I can confidently say that I know more than the agents. For absolute beginners, I’d suggest using Markdown or one of the more popular web frameworks instead.

HTML Syntax

Pure HTML isn’t aware of types. It only knows strings and tags. It doesn’t support calculations of any sort, ² and it losely inherits XML’s syntax. ³ While HTML and XML are extremely good at describing mixed content, writing them is a pain, especially if you don’t have support from a modern editor that does the cleanup for you.

I don’t like the syntax of HTML and JavaScript. My point from the very first time I used HTML was HTML shouldn’t be edited by hand. It should be procedurally generated by templating engines, even by using other langauges. And that was exactly what developers did. Frameworks, both frontend and backend, all generates HTML upon user requests or when exporting the site. That being said, HTML’s syntax remains and sticks. You’d see <foo></foo> with the closing tag everywhere. ⁴ and the way frameworks such as Astro mixed JavaScript into HTML made the situation even worse: JavaScript’s syntax is also confusing. Functions can be imperative, the ternary operator is weird, and confusing comparison and type casting. All of which have repelled me from writing websites.

Typst

Typst is mostly known as the “modern L a T e X alternative”, which is true. But it can do more than just producing PDFs.

Postprocessing HTML

↑ The shebang:
```
#!/usr/bin/env -S typst compile --features bundle,html --format bundle
```
. In practice, it is probably better to setup a Justfile or Makefile to manage the commands. In my case, I only have two commands to execute during development: build, which builds the site, and serve, which serves the site. I wanted to avoid pulling in an extra dependency (even including make! Which is installed by default on many devices), so in this case I just have dist.typ with a shebang, and an extra serve file which looks like this:
```
#!/usr/bin/env bash
typst watch --features bundle,html --format bundle ./dist.typ --pretty
```
↑ JavaScript is an option, but it is a bad option.
↑ XHTML is the better kid in the classroom.
↑ An argument is that the closing tag makes it easier for the programmer to inspect the type of the block without having to scroll up. This would’ve made sense if LSPs were not a thing. Modern LSPs (such as rust-analyzer) support showing functions names at the end of the function’s scope. This extra closing tag is just extra maintenance burden.