I initially tried making a modal Markdown editor to allow myself to edit my notes without changing their representation. However, looking at the strange corners of Markdown syntax I had to handle, with millions¹ of redundant ways to make bullet points and strange alternative heading types² , convinced me to search for articles to confirm my growing Markdown disapproval.

With my dislike of Markdown now supported by credible sources, I decided to convert all my 400 notes to Typst, the LaTeX replacement with Markdown-like syntax. I will describe that conversion process in this post to help anyone else converting many Markdown documents.

Setup

I used the universal document converter Pandoc to automate the conversion. To minimize the cost of mistakes, I wrote a Python script that would run each command-line tool, and save the output in a folder separate from my actual notes folder. This separation protected my actual notes from modification before I became certain about my conversion process.

The main part of my Python script initially looked like this:

main.py:

old_dir = Path("./old")
new_dir = Path("./new")

if new_dir.exists():
    shutil.rmtree(new_dir)
    print("cleared new_dir")

new_dir.mkdir(parents=True, exist_ok=True)

md_names = [
    "md_to_typ_test.md",
    "-hackerman--brot_rich_content_test.md",
]

for md_name in md_names:
    print("converting", md_name)

    md_file = old_dir / md_name
    content = md_file.read_text(encoding="utf-8")
    modified_content = process_content(content)

    typ_file = new_dir / md_file.with_suffix(".typ").name
    typ_file.write_text(modified_content, encoding="utf-8")

    print("compiling with typst")
    path = str(typ_file)
    call_typst(path)
    call_typstyle(path)

I started by only converting two test Markdown files containing examples of richly formatted content. For each of those files, I first used Pandoc to convert the content to Typst, ensured that the results compiled by calling Typst, and finally fixed formatting with the formatter typstyle.

This infrastructure allowed me to quickly iterate on my conversion process, giving me the ability to easily change arguments for all command-line tools and quickly see the conversion results.

Results

After much iteration, I created a process that worked correctly for almost all my notes.

Preprocessing

Tiptap denotes underlines with the nonstandard ++ syntax, for example ++I am underlined++. I used an evil RegEx to solve this problem, using python to replace these markers with the bracketed spans notation that Pandoc understands.

The below regex replaces text like ++hello world++ with [hello world]{.underline}.

main.py:

def preprocess_markdown(md_text: str) -> str:
    md_text = re.sub(r"(?<!\\)\+\+(.+?)(?<!\\)\+\+", r"[\1]{.underline}", md_text)
    return md_text

Pandoc command

My final Pandoc command looked like this:

pandoc
  -f gfm-gfm_auto_identifiers+bracketed_spans+smart-autolink_bare_uris
  -t typst
  --lua-filter=filter.lua

I converted from Github-Flavored Markdown (specified by setting -f to gfm), because it better fit Tiptap’s Markdown export. I also configured some Pandoc extensions on GFM, and added a Lua filter to fix edge cases.

Pandoc extensions

• I disabled the gfm_auto_identifiers Pandoc extension by appending ‑gfm_auto_identifiers (you can read this syntax as “subtract gfm_auto_identifiers”) so that each heading wouldn’t have an associated Typst label.
• I enabled the bracketed_spans extension to handle the underlines I created in preprocessing.
• I enabled the smart extension so that Pandoc would correctly interpret quotes matching curly quotes, and not escape them when converting to Typst, preventing the problem of "hello world" turning into \"hello world\".
• I disabled the autolink_bare_uris extension to pass plain links to Typst as plain text.

Lua filter

I also used a Pandoc Lua filter by specifying the --lua-filter option, allowing me to make precise adjustments by writing arbitrary Lua code with access to Pandoc’s internal representation of elements.

The Lua filter I wrote grew into complexity to shoulder the heap of edge cases in the large number of notes I’d written. It consists of two passes, convert_html and modify_elements. Pandoc knows the order to run the filters because Lua tables are ordered by insertion.

filter.lua:

local convert_html = {
  -- ...
}

local modify_elements = {
  -- ...
}

return { convert_html, modify_elements }

The convert_html filter consists of only one selector which finds HTML tables and forces Pandoc to parse them as actual tables.

filter.lua:

local convert_html = {
  RawBlock = function(raw)
    if raw.format:match 'html' and raw.text:match '%<table' then
      return pandoc.read(raw.text, raw.format).blocks
    end
  end
}

The modify_elements filter has many more selectors.

• The first selectors force Pandoc to render strong and emphasized elements using the dedicated syntax, turning #strong(hello) #emph(world) into *hello* _world_.

  filter.lua:

  local modify_elements = {
    Strong = function(el)
      local inlines = { pandoc.RawInline('typst', '*') }
      for _, item in ipairs(el.content) do
        table.insert(inlines, item)
      end
      table.insert(inlines, pandoc.RawInline('typst', '*'))
      return inlines
    end,
  
    Emph = function(el)
      local inlines = { pandoc.RawInline('typst', '_') }
      for _, item in ipairs(el.content) do
        table.insert(inlines, item)
      end
      table.insert(inlines, pandoc.RawInline('typst', '_'))
      return inlines
    end,
    -- ...
  }

• The Link filter turns links without bodies and links with bodies identical to their sources into plaintext links that Typst recognizes, allowing [https://julianlbauer.com](https://julianlbauer.com) to become https://julianlbauer.com instead of #link("https://julianlbauer.com")[https://julianlbauer.com].

  filter.lua:

  local modify_elements = {
    -- ...
    Link = function(el)
      local content_text = pandoc.utils.stringify(el.content)
  
      if content_text == el.target or content_text == "" then
        return pandoc.RawInline('typst', el.target)
      else
        return el
      end
    end,
    -- ...
  }

• The Math filter passes the content inside math elements directly to Typst, because I had already created a custom Tiptap plugin that used Typst math syntax inside Typst using tex2typst. I also included some evil find-and-replace lines to fix tex2typst’s inconsistencies with Typst.

  filter.lua:

  local modify_elements = {
    -- ...
    Math = function(el)
      local modified_text = string.gsub(el.text, "cdot", "dot ")
      modified_text = string.gsub(modified_text, "int ", "integral ")
      modified_text = string.gsub(modified_text, "int%%^", "integral^")
      modified_text = string.gsub(modified_text, "int_", "integral_")
      modified_text = string.gsub(modified_text, "empty", "emptyset")
      modified_text = string.gsub(modified_text, " sub ", " subset ")
      if el.mathtype == 'InlineMath' then
        return pandoc.RawInline('typst', '$' .. modified_text .. '$')
      else
        return pandoc.RawInline('typst', '$ ' .. modified_text .. ' $')
      end
    end,
    -- ...
  }

• The Span filter adds underlines to the spans created in preprocessing.

  filter.lua:

  local modify_elements = {
    -- ...
    Span = function(el)
      if el.classes:includes('underline') then
        return pandoc.Underline(el.content)
      end
    end,
    -- ...
  }

• The Table filter removes the #figure() wrapping around tables, and uses evil RegExes to remove some table boilerplate I found unecessary.

  filter.lua:

  local modify_elements = {
    -- ...
    Table = function(elem)
      elem.attr.classes:insert('typst:no-figure')
      elem.attr.attributes['typst:figure:kind'] = 'none'
      local typst_code = pandoc.write(pandoc.Pandoc({elem}), 'typst')
      typst_code = typst_code:gsub("%s*align:%s*%([^%)]+%),?\n", "\n")
      typst_code = typst_code:gsub("%s*table%.hline%(%),?\n", "\n")
      return pandoc.RawBlock('typst', typst_code)
    end
  }

Postprocessing

I discovered that Pandoc overcautiously escaped the second slash in the https:// of links to prevent creating a // typst comment, an unnecessary and uglifying change that made all bare links in the resulting Typst look like http:/\/julianlbauer.com instead of http://julianlbauer.com.

As a final evil hack, I used find-and-replace on the resulting source code to remove that extra backslash.

main.py:

def postprocess_typst(text: str) -> str:
    text = text.replace("https:/\\/", "https://")
    return text

Manual adjustments

Tragically, there were a few unavoidable manual adjustments I had to make. Before switching my math to Typst, I had written a quarter dozen notes with LaTeX math. I converted those equations to Typst by hand.

Conclusion

I had to write much more code than I expected, due to the verbosity of Pandoc’s default Typst output and the nonstandard Markdown output of my Tiptap editor. Luckily, my process was still much faster than manually converting each note.

You can see my conversion code on Github. I hope this article can act as an example for new Pandoc users facing big document conversion projects!

What you get

This configuration creates two new keyboard shortcuts you can use when editing Typst files:

The previewing window

• Has all the preview features for the Typst language server Tinymist, including instant previewing as you type, jumping to source on-click, and dark theme
• Spawns as a seperate window without distracting browser elements like tabs and search bars
• Works without conflicting with other preview windows spawned from other Helix instances

Configuration steps

1. Make sure you’ve installed the Typst language server Tinymist

2. Open your global Helix languages file, and append:

   ~/.config/helix/languages.toml:

   [language-server.tinymist]
   command = "tinymist"
   config.preview.background.enabled = true
   config.preview.background.args = ["--data-plane-host=127.0.0.1:0"]

   These lines configure Tinymist to start a preview server at a random port once you’ve opened your first Typst file, as specified by setting the data-plane-host port to 0.

3. Make sure you’ve installed Nushell—a modern shell and programming language intended to replace bash, zsh, and other shells—so that you can run the preview-opening script.¹

4. Create a file typst-preview.nu somewhere, perhaps in your Helix config directory, with the contents:

   ~/.config/helix/typst-preview.nu:

   let helix_pid = (ps | where pid == $nu.pid | first).ppid
   
   let tinymist_proc = ps
   | where ppid == $helix_pid
   | where name =~ tinymist
   | first
   if $tinymist_proc == null {
       print "tinymist proc is null"
   } else {
       let tinymist_entry = lsof -i -P -n
       | from ssv --minimum-spaces 1
       | where PID == ($tinymist_proc.pid |
       into string)
       | first
       # should be `google-chrome --app=("http://" + $tinymist_entry.NAME)` on Linux
       ^open -na "Google Chrome" --args --app=("http://" + $tinymist_entry.NAME)
   }

   This script finds your Helix instance’s process ID, finds the child Tinymist process that the Helix instance spawned, and looks up the address of the previewing server based on the child’s process ID.

   The final open command opens the address in Chrome, using the --app flag of Chromium browsers to hide tabs and other superfluous UI elements.²

5. Open your Helix config file, and append:

   ~/.config/helix/config.toml:

   [keys.normal]
   "C-S-p" = ':sh nu ~/.config/helix/typst-preview.nu'
   "C-p" = ':lsp-workspace-command tinymist.pinMain "%sh{realpath %{buffer_name}}"'

   These lines create the keyboard shortcuts described above.

Credits

Most of the config comes from sijo’s reply in the Typst forums, without which I wouldn’t have understood how to make Tinymist preview at a random port. Thank you!

My improvements consist of

• Letting you open the preview server intentionally with a shortcut instead of having Tinymist open your browser automatically on startup and annoyingly steal your focus
• Opening the preview in a dedicated UI-less window instead of cluttering your browser’s tabs³

I hope this helps!

As part of a project for discrete math, I formally verified that insertion sort actually sorts lists of natural numbers. I wanted to write a thorough walkthrough of each part of the code to provide a resource on how to prove things with dependently typed languages.

Many of the guides I saw either only showed extremely basic functionality or glossed over the specifics of their proofs, making the relationship between proof and program harder to understand.

Additionally, Idris’ large feature set made much of the code I saw online difficult to understand. For this guide, I used only basic features language features¹ to make each function implementation as consistent and comprehensible as possible.

For those new to dependently-typed languages, I would recommend looking at the Idris 2 Crash Course and the Lean Natural Number Game (the concepts apply to Idris as well).

Definitions

Standard library

First, to refresh our knowledge of Idris’s basic types, we look at the definition of natural numbers and lists provided by the standard library.

data Nat : Type where
  Z : Nat
  S: Nat -> Nat

We define natural numbers as an enum with two variants: the zero base case value Z and the successor S that wraps another natural number. Thus, we represent 0 as Z, 1 as S Z, 3 as S (S (S Z)), continually incrementing numbers by wrapping them in layers of successors.

data Vect : Nat -> Type -> Type where
  Nil : Vect 0 elem
  (::) : elem -> Vect len elem -> Vect (S len) elem

Looking at the first line of code, data Vect : Nat -> Type -> Type where, we parameterize our definition of Vect over the list’s length and the type of the contained items. Then, we have a base case constructor of an empty list, and a constructor that adds an element to an already existing list while keeping the type’s length information correct.

We also need a way to order our natural numbers.

data LTE : (n, m : Nat) -> Type where
  LTEZero : LTE Z    right
  LTESucc : LTE left right -> LTE (S left) (S right)

We define evidence LTE, parameterized over two natural numbers. Constructing an element of type LTE x y proves that x <= y. Our base case, LTEZero, simply states that zero is less than or equal to any other natural number, because it’s the smallest number. LTESucc allows us to increment both of the numbers on each side of the inequality, allowing us to express any possible LTE relationship between two natural numbers.

Sorted

In order to prove that our insertion sort algorithm sorts, we need a definition of sortedness.

data Sorted : (xs : Vect n Nat) -> Type where
  SortedZero: Sorted Nil
  SortedOne: (x : Nat) -> Sorted (x::Nil)
  SortedMany: (x : Nat) -> (y : Nat) -> (ys : Vect n Nat) ->
    (LTE x y) -> Sorted (y :: ys) ->
    Sorted (x :: (y :: ys))

We parameterize our definition of Sorted over a given list of natural numbers. Thus, if we can construct a value of type Sorted xs, then we have proven that the list xs is sorted.

In this definition, we have two base cases SortedZero and SortedOne: if our list contains zero or one items, we already know that it is sorted.

Our recursive SortedMany definition is more complicated, but becomes easier to understand if you read it backwards. The basic idea is that, given a list containing at least two elements $\left[𝑥,𝑦,\dots \right]$, represented as (x :: (y :: ys)) in the above proof, you know it is sorted if both

1. $\left[𝑦,\dots \right]$ is sorted
2. $𝑥\le 𝑦$

Reading the SortedMany constructor forwards gives a more constructive view of the theorem it represents. Instead of proving that a given list is sorted, we can think of this constructor as taking an element x, y, a list ys, a proof that y::ys is sorted, and a proof that x <= y, and outputting a proof that a new list x::(y::ys) is sorted.

Permutation

In addition to proving that our insertion sort algorithm sorts, we also need to prove that the elements in the outputted list are the same as those in the inputted list; in other words, we must prove that the output is a permutation of the input. Thus, we create a definition of permutation.

data Permutation : (xs: Vect n Nat) -> (ys: Vect n Nat) -> Type where
  PermutationZero: Permutation [] []
  PermutationGrow: (as, bs: Vect n Nat) -> (x : Nat) ->
    Permutation as bs -> Permutation (x::as) (x::bs)
  PermutationSwap: (as, bs : Vect n Nat) -> (a, b : Nat) -> Permutation as bs ->
    Permutation (a::(b::as)) (b::(a::bs))
  PermutationTrans: (as, bs, cs : Vect n Nat) ->
    Permutation as bs -> Permutation bs cs -> Permutation as cs

Here, we parameterize our definition of Permutation over two lists, claiming that a construction of a value of type Permutation xs ys proves that ys permutes xs.

Our base case PermutationZero simply states that empty lists permute each other. Both PermutationGrow and PermutationSwap claim that larger lists permute each other given that smaller lists do as well; PermutationGrow claims that two permutations with the same element added to the front permute each other, and PermutationSwap claims that two permutations with the same two elements added to the front in different orders permute each other. PermutationTrans just states that permutation is transitive, meaning that if $𝑥$ permutes $𝑦$ and $𝑦$ permutes $𝑧$ then $𝑥$ permutes $𝑧$.

Elem

To make some of our proofs easier, we need a way to state that x is an element of a list.

data Elem : (x : a) -> (xs : Vect n a) -> Type where
  Here  : Elem x (x :: xs)
  There : Elem x xs -> Elem x (y :: xs)

Our definition has a base case of Here if x is the first element of the list, and There if it is a later element of the list. So to construct a proof that x is in xs = [x, ...], we would simply write Here, and to construct a proof that x is in xs = [z, y, x, ...] we would write There (There Here).

Theorems

When thinking through how to prove our theorem, I found it easiest to start from high-level functions and create smaller functions with the correct type declarations but with holes as placeholders for their bodies.

insertion​Sort

The highest-level theorem is, of course, our insertionSort function. First, let’s create the functions type declaration. Note that this type declaration corresponds to the theorem that we are stating by the Curry-Howard isomorphism:

insertionSort : (inList : Vect n Nat)
  -> (outList : Vect n Nat ** (Sorted outList, Permutation inList outList))

Here, we take in some list inList, and output an outList dependently-paired with a proof that outList is sorted and that outList permutes inList. Stating this function as a theorem, we are saying that

Let inList be a list. There exists a sorted list outList that is a permutation of inList.

Now, let’s look at our function implementation. By the Curry-Howard isomorphism, the implementation corresponds to the proof of our theorem. First, we handle the case of an empty list:

insertionSort [] = ([] ** (SortedZero, PermutationZero))

The SortedZero constructor proves that an empty list is sorted, and PermutationZero proves that both empty lists permute each other.

The more interesting case comes when the list contains at least one element.

insertionSort (x::xs) =
  let
    recursiveCase : (xsSorted : Vect _ Nat ** (Sorted xsSorted, Permutation xs xsSorted)) = insertionSort xs
    (xsSorted ** (sor1, perm1)) = recursiveCase
    insertRet : (xsSortedInserted : Vect _ Nat ** (Sorted xsSortedInserted, Permutation (x::xsSorted) xsSortedInserted))
      = insert xsSorted sor1 x
    (xsSortedInserted ** (sor2, perm2)) = insertRet
    perm3 : Permutation (x :: xs) (x :: xsSorted) =
      PermutationGrow xs xsSorted x perm1
    permRet : Permutation (x::xs) (xsSortedInserted) =
      PermutationTrans (x::xs) (x::xsSorted) xsSortedInserted perm3 perm2
  in (xsSortedInserted ** (sor2, permRet))

First, we recursively sort the tail of our list, xs, storing the result in xsSorted. Then, we use a new function, insert, to insert our head into the xsSorted. Our insert function outputs a new list we call xsSortedInserted, and conveniently provides proof that xsSortedInserted is sorted and that xsSortedInserted permutes x::xsSorted (another way of saying that xsSortedInserted consists of all elements from xsSorted and x).

The final part of the proof consists of proving that the input list, x::xs, permutes the output list xsSorted. First, we use the fact that we know that xs permutes xsSorted to prove that x::xs permutes x::xsSorted with PermutationGrow, storing this proof in perm3. That gives us two permutation proofs

1. x::xs permutes x::xsSorted
2. x::xsSorted permutes xsSortedInserted

These two permutations perfectly match our PermutationTrans constructor, allowing us to construct a proof that x::xs permutes xsSortedInserted, completing our function.

Now we’ve completed our proof! All we need to do is finish that insert function we assumed existed.

insert

We again start with the type declaration:

insert : (inList : Vect n Nat) -> (Sorted inList) -> (x : Nat)
  -> (outList : Vect (S n) Nat ** (Sorted outList, Permutation (x::inList) outList))

Here, we take some sorted list inList and some element x, and output a sorted list that permutes x::inList.

We again have an easy base case if the list is empty:

insert [] sor x = ([x] ** (SortedOne x, permutationId [x]))

Here, we use a utility theorem, permutationId, that proves that two identical lists permute each other by repeatedly applying PermutationGrow.

permutationId : (xs : Vect n Nat) -> Permutation xs xs
permutationId [] = PermutationZero
permutationId (x::xs) = PermutationGrow xs xs x (permutationId xs)

This theorem may seem obvious, but Idris’ type system requires that we prove it.

Unfortunately, the case where the list contains more than one element becomes more complicated.

First, we define a new function lteTotal that proves an obvious fact: for two natural numbers $𝑥$ and $𝑦$, either $𝑥\le 𝑦$ or $𝑦\le 𝑥$.

lteTotal : (x, y : Nat) -> Either (LTE x y) (LTE y x)
lteTotal Z Z = Left LTEZero
lteTotal Z (S m) = Left LTEZero
lteTotal (S n) Z = Right LTEZero
lteTotal (S n) (S m) =
  case lteTotal n m of
    Left p => Left (LTESucc p)
    Right p => Right (LTESucc p)

Here we have a bunch of base cases whenever one of the natural numbers is zero, and a recursive case that uses LTESucc if both numbers are nonzero.

Going back to our insert function, we apply lteTotal to compare the element we want to insert, x, and the first element y of our input list y::ys.

insert (y::ys) sor x =
  case lteTotal x y of
    Left prf =>
      let
        retSor = SortedMany x y ys prf sor
        ret = (x::(y::ys) ** (retSor, permutationId (x::(y::ys)) ))
      in ret
    Right prf =>
      let
        ysSorted = sortedImpliesSortedSmaller y ys sor
        recursiveCase = insert ys ysSorted x
        (x_ys ** (sor1, perm1)) = recursiveCase
        y_x_ysSorted = yLtXAndYsImpliesYLtXYs x y ys x_ys prf sor sor1 perm1
        intermediatePerm: Permutation (y::(x::ys)) (y::x_ys) = PermutationGrow (x::ys) (x_ys) y perm1
        retPerm: Permutation (x::(y::ys)) (y::x_ys) =
          PermutationTrans
            (x::(y::ys)) (y::(x::ys)) (y::x_ys)
            (PermutationSwap ys ys x y (permutationId ys)) intermediatePerm
        ret = (y::x_ys ** (y_x_ysSorted, retPerm))
      in ret

If x is smaller than or equal to y, then putting x at the start of our list will keep it sorted. We handle this possibility in the Left case, where we use the SortedMany constructor to prove that x::(y::ys) is sorted given that x $\le$ y.

The more interesting case happens when x is larger than y, which we handle in the Right case.² First, we use a utility function sortedImpliesSortedSmaller to show that ys is sorted, which is obviously true because y::ys is sorted.

sortedImpliesSortedSmaller : (x: Nat) -> (xs : Vect n Nat) -> (Sorted (x::xs)) -> Sorted xs
sortedImpliesSortedSmaller x [] _ = SortedZero
sortedImpliesSortedSmaller x (y::ys) (SortedMany x y ys _ sor) = sor

Because x is greater than y, we insert x somewhere in the part after y using our insert function. We call the list resulting from that insertion x_ys. Finally, we attach y to the front of x_ys, creating our final list y::x_ys. The only remaining task is constructing the proofs that y::x_ys is sorted and is a permutation of x::(y::ys).

To prove permutation, we use PermutationGrow to prove that y::(x::ys) permutes y::x_ys given that we know that x::ys permutes x_ys from our insertion. Then, we directly apply the PermutationSwap constructor to see that x::(y::ys) permutes y::(x::ys), and finally use PermutationTrans to combine those two permutations and create our final permutation.

To prove sortedness, we use a magical theorem yLtXAndYsImpliesYLtXYs to show that y::x_ys, a theorem complex enough to deserve its own section!

y​Lt​X​And​Ys​Implies​Y​Lt​X​Ys

As the theorems got more complex, naming them also became harder, leading to the mess of characters heading this section. The type declaration this function shares the complexity of its name:

yLtXAndYsImpliesYLtXYs:
  (x, y: Nat) -> (ys: Vect n Nat) -> (x_ys : Vect (S n) Nat) ->
  (LTE y x) -> (Sorted (y::ys)) -> (Sorted x_ys) -> (Permutation (x::ys) x_ys) -> (Sorted (y::x_ys))

I think the best way to understand this function is to read it as a theorem

Theorem: Let x, y be elements and ys be a list. Let x_ys be a list that contains x and all elements in ys in some order. If y $\le$ x and y::ys is sorted (which means that y $\le$ all elements in ys), then the list y::x_ys is sorted.

Due to the use of magical functions that abstract away details, the implementation of this function remains quite small.

yLtXAndYsImpliesYLtXYs:
  (x, y: Nat) -> (ys: Vect n Nat) -> (x_ys : Vect (S n) Nat) ->
  (LTE y x) -> (Sorted (y::ys)) -> (Sorted x_ys) -> (Permutation (x::ys) x_ys) -> (Sorted (y::x_ys))
yLtXAndYsImpliesYLtXYs x y ys (f::x_ysTail) yLteX y'ysSor x_ysTailSor x'ysPermX_ys =
  let
    yLteF =
    case elOfListIsInPermOfList f (permutationRev x'ysPermX_ys) Here of
      Here => replace {p=(\k => LTE y k)} Refl yLteX
      There elem => yAfterXInSortedListImpliesXLtY y f ys y'ysSor elem
    in SortedMany y f x_ysTail yLteF x_ysTailSor

Here, we are trying to prove that adding y to the front of the sorted list f::x_ysTail (also know as x_ys in the type declaration) will create another sorted list.

Before getting to the main idea of our proof, we have to reverse the permutation x'ysPermX_ys constructing Permutation x_ys (x::ys) from Permutation (x::ys) x_ys. To prove this obvious fact, we have create a tiny utility theorem:

permutationRev : Permutation xs ys -> Permutation ys xs
permutationRev (PermutationZero) = PermutationZero
permutationRev (PermutationGrow as bs x p) =
  (PermutationGrow bs as x (permutationRev p))
permutationRev (PermutationSwap as bs a b p) =
  PermutationSwap bs as b a (permutationRev p)
permutationRev (PermutationTrans as bs cs perm1 perm2) =
  PermutationTrans cs bs as (permutationRev perm2) (permutationRev perm1)

First, we use the theorem elOfListIsInPermOfList to show that, because f::x_ysTail is a permutation of x::ys, then f must be an element of the list x::ys. That means f must either:

1. Be equal to the head x of x::ys
2. Be an element of the tail ys of x::ys

In both cases, we create evidence yLteF of type idris LTE y f to show that y is less than or equal to the first element of f::x_ysTail, which is enough to construct a SortedMany that completes the proof.

In the case that f equals x, we can use the fact that we know that y $\le$ x to show that y $\le$ f by substitution. We do this substitution with Idris’ built in replace function.

In the case that f is in ys, we use another theorem yAfterXInSortedListImpliesXLtY to show that y $\le$ f.

el​Of​List​Is​In​Perm​Of​List

This theorem tells us that given some list containing element x, any permutation of that list will also contain x.

elOfListIsInPermOfList: (a : Nat) -> Permutation as cs -> Elem a as
  -> Elem a cs
elOfListIsInPermOfList c (PermutationSwap xs ys a b p) elem = case elem of
  Here => There (Here)
  There (Here) => Here
  There (There pos) => There (There (elOfListIsInPermOfList c p pos))
elOfListIsInPermOfList l (PermutationGrow xs ys x p1) elem = case elem of
  Here => Here
  There elem => There (elOfListIsInPermOfList l p1 elem)
elOfListIsInPermOfList a (PermutationTrans as bs cs p1 p2) aElemAs = let
  aElemBs : (Elem a bs) = elOfListIsInPermOfList a p1 aElemAs
  in elOfListIsInPermOfList a p2 aElemBs

Here, we simply look at every possible Permutation constructor, recursively finding out where the element is. Note that we don’t need to handle PermutationZero because idris has statically determined that passing in PermutationZero would be impossible for lists that contain elements.

y​After​X​In​Sorted​List​Implies​X​Lt​Y

We’ve arrived at our final theorem, another heap of messy characters. The idea of this theorem, however, is simple: if an element y is in a list xs, and the list x::xs is sorted, then x <= y. In other words, if an element y comes after x in a sorted list, then x <= y.

yAfterXInSortedListImpliesXLtY: (x, y : Nat) -> (xs : Vect n Nat) -> (Sorted (x::xs)) -> (Elem y xs)
  -> (LTE x y)
yAfterXInSortedListImpliesXLtY x y (y::xs) (SortedMany x y xs prfLte sor) Here = prfLte
yAfterXInSortedListImpliesXLtY x y (f::xs) (SortedMany x f xs prfLte sor) (There n) = let
  fLteY : LTE f y = yAfterXInSortedListImpliesXLtY f y xs sor n
  xLteF : LTE x f = prfLte
  in transitive xLteF fLteY

First, note that because we have at least two elements in our list (x and y), Idris can statically guarantee that we only need to handle the SortedMany constructor.

Our proof splits on two cases:

1. If y happens to be the first element in xs, then we can just return the LTE evidence embedded in our proof of sortedness.
2. If y is not the first element in xs, then we call the first element f, and recursively prove that f <= y. Then we use the LTE in our proof of sortedness to show that x <= f, and use the standard-library-defined transitive³ property of inequality to show that x <= f.

Conclusion

With all these theorems in place, our program finally compiles, which—by the guarantees of Idris’ type system—proves that our sorting algorithm works correctly. Creating an actual proof is a powerful statement: assuming Idris has no bugs, our program will sort any list of natural numbers, no matter the size of the list or the size of the numbers. We know this without any testing, fuzzing, or manual inspection—as long as we trust our definitions, the fact that the program compiles provides total assurance. You can find the complete source code on GitHub.

Throughout this guide, I paired thorough proof explanations and programs that express those proofs. I intended for these pairings to help clarify the main idea of the Curry-Howard correspondence:

Types correspond to propositions, programs correspond to proofs

I hope it helps aspiring dependent typers learn!

As a way to learn more about benchmarking and writing code that go fast, I wrote a Rust program to find all the disarium numbers as quickly as possible. I got the program to check all 18446744073709551616 u64s in just over 12 seconds on my MacBook Pro M4.

Problem scope

To understand the scope of this problem, I did some preliminary research and realized that there are a finite number of disarium numbers, because once you reach 23 digits, the largest possible digit-power-sum only has 22 digits:

99999999999999999999999 <- 23 digit number with max digit sizes
9960805384609063732919  <- digit-power-sum of 99999999999999999999999

This digit difference means that there cannot exist any disarium numbers with more than 22 digits because all digit-power-sums after that will be too small.

In reality, there are only 20 disarium numbers, and all of them fit into a u64. To make implementation easier, I decided to benchmark checking all u64s instead of using u128s and going to 22 digits, although I also checked the runtime with u128s in the end as well.

Basic approach

The easiest way to find all disarium numbers is to loop through every integer, break it into digits, and check if the digit-power-sum equals the original number to see it’s a disarium number.

A small optimization is to store and increment the digits separately so that you don’t have to repeatedly extract digits.¹ I implemented this version as a starting point.

src/lib.rs:

fn add_one(digits: &mut [u8], number: &mut u64) {
    *number += 1;
    for i in (0..digits.len()).rev() {
        if digits[i] < 9 {
            digits[i] += 1;
            return;
        }
        digits[i] = 0;
    }
}

fn check_disarium(digits: &[u8], number: u64) -> bool {
    let number_cmp: u64 = digits
        .iter()
        .skip_while(|&n| *n == 0)
        .enumerate()
        .map(|(i, n)| (*n as u64).pow(i as u32 + 1))
        .sum();
    number_cmp == number
}

pub fn find_disarium(bound: u64) -> impl Iterator<Item = u64> {
    let mut digits = [0; 10];
    let mut number: u64 = 0;
    std::iter::from_fn(move || {
        while number < bound {
            add_one(&mut digits, &mut number);
            if check_disarium(&digits, number) {
                return Some(number);
            }
        }
        None
    })
}

Checking the first 100 million integers gives

1
2
3
4
5
6
7
8
9
89
135
175
518
598
1306
1676
2427
2646798

This approach gives us 18 out of 20 numbers in about 1 second. Unfortunately, the final two are slightly larger, and will take some more optimization to reveal in a reasonable amount of time.

Benchmarking

To properly measure performance improvements, I installed the benchmarking library criterion. This library makes measuring benchmark differences easier and more reliable. I wrote a simple benchmark on the first 1 million numbers:

benches/benchmark.rs:

pub fn criterion_benchmark(c: &mut Criterion) {
    c.bench_function("disarium 1 mil", |b| {
        b.iter(|| find_disarium(black_box(1_000_000)).collect::<Vec<_>>())
    });
}

Table of powers

Because there are only 10 possible digits and 20 possible digit places, we can precalculate all possible powers for each digit and store them in a table at compile time.

src/lib.rs:

const DIGIT_POWERS: [[u64; 20]; 10] = {
    let mut table = [[0u64; 20]; 10];
    let mut d = 0;
    while d < 10 {
        let mut p = 0;
        while p < 20 {
            table[d][p] = (d as u64).pow((p + 1) as u32);
            p += 1;
        }
        d += 1;
    }
    table
};
fn exp_digit(digit: usize, position: usize) -> u64 {
    DIGIT_POWERS[digit][position]
}

In addition to helping “improve code”, using a benchmarking library like criterion has a very good benefit of gamifying optimization. The dopamine-rich green dripping off of improving benchmarks provides great motivation to continue coding.

disarium 1 mil          time:   [2.0033 ms 2.0059 ms 2.0086 ms]
                        change: [−71.564% −71.299% −71.063%] (p = 0.00 < 0.05)
                        Performance has improved.

Our optimization seems to have worked. So good!

Freezing digits

Tragically, reducing the work we do to check each number will still end up slow if we do that work on all 18,446,744,073,709,551,616 u64s. I decided to look for ways to exclude ranges of numbers and save time.

To help look for patterns, I used a quick python script to create a graph of the differences between each number and its digit-power-sum. I’ve recreated this graph:

This graph helped me realize was that lower-place digits have the largest impact on the digit-power-sum because they are powered to the highest number. In the graph, we can see distinct groups of 10 numbers, each abruptly ending with a jump downwards when the 9 digit turns into a 0. We can explain these groups by remembering the digit-power-sum formula; the last digit will always be powered to the highest power, so it has the biggest impact.

Because lower-place digits have the biggest impact, I decided to see how isolating numbers ending in the same digit—for example, digit 8—would look.

This isolation reveals a pattern: it looks like for two-digit numbers ending with 8, there’s only a small window between about 60 and 80 where finding a disarium number is possible. Going backwards from the window, the difference seems to get larger and larger. We see a similar pattern going forwards, where the difference seems to get larger in the negative direction.

We can justify this intuition mathematically. For two-digit numbers ending with 8, we can calculate the minimum possible digit-power-sum by minimizing the unknown first digit. The minimum possible first digit that doesn’t make the number a one-digit number is 1.

Because the minimum possible number we can make is 65, there’s no reason to check 58, 48, or any other number below 65 that has two digits and ends with 8.

We can also find an upper bound by maximizing the first digit, setting it to 9 instead of 1.

By the same logic as before, it makes no sense to check 78, 88, or any other number larger than 73 (that has two digits and ends with 8).

Thus, we have mathematically proven that the only possible disarium candidates for two-digit numbers ending in eight must be in the range $\left[65,73\right]$. The only number we have to check is 68, reducing our work from checking 9 different numbers to just checking 1.

We can generalize this approach to work on multiple low-place digits. Whenever we want to check all $𝑛$-digit numbers,

1. We choose some integer $𝑚$, where $𝑚\le 𝑛$, for the number of low-place digits we want to “freeze”. For example, for 5-digit numbers, we could choose to “freeze” 2 digits.
2. We go through all possible frozen digits. Continuing our example, all possible pairs of 2 digits are $\left(0,0\right),\left(0,1\right),\left(0,2\right),\dots ,\left(9,9\right)$.

3. For each frozen digit set…

   1. We calculate the minimum and maximum digit-power-sums. If our digits are $\left(8,9\right)$, then our minimum is $\text{digit-power-sum}\left(10089\right)=63146$ and our maximum is $\text{digit-power-sum}\left(99989\right)=63964$.
   2. We check only numbers in [minimum, maximum]. For our example, we would only have to check numbers in the range $\left[63146,63964\right]$. This reduces the number of numbers we need to check from 900 to just 8.

You can see how many checks we save for different digit amounts and frozen digits with the calculator below.

Implementing this algorithm was the most significant optimization in the project. The actual implementation was cumbersome, requiring splitting the numbers into different digit count buckets and dealing with correctly handling maximum and minimum bounds. To simplify the code, I created a Digit struct that encapsulated some of the number methods.

Here’s the most important snippet, the function that calculates the maximum and minimum bounds given some frozen digits and searches that range for disarium numbers.

src/lib.rs:

fn disarium_for_digit_count_with_frozen(
    digit_count_unfrozen: u32,
    bound: u64,
    frozen_digits: [Digit; NUM_FROZEN],
) -> Vec<u64> {
    let digit_count = digit_count_unfrozen + NUM_FROZEN as u32;

    let min_digits =
        Digits::from_number(10u64.pow(digit_count - 1)).with_overwritten(&frozen_digits);

    let max_digits =
        Digits::from_number(10u64.pow(digit_count) - 1).with_overwritten(&frozen_digits);

    let start_digits =
        Digits::from_number(min_digits.exp_by_index()).with_overwritten(&frozen_digits);
    let end_digits =
        Digits::from_number(max_digits.exp_by_index()).with_overwritten(&frozen_digits);

    let start = start_digits.to_number().max(min_digits.to_number());
    let end = end_digits
        .to_number()
        .min(max_digits.to_number())
        .min(bound);

    search_range(start, end, NUM_FROZEN as u32)
}

Our cumbersome implementing is rewarded by criterion with more beautiful green numbers!

disarium 1 mil          time:   [33.079 µs 33.174 µs 33.260 µs]
                        change: [−98.354% −98.350% −98.346%] (p = 0.00 < 0.05)
                        Performance has improved.

Parallel processing

After implementing the more optimized algorithm, I decided to improve performance by splitting my work across multiple threads. For every digit length $𝑛$, I split the ${10}^{𝑚}$ frozen digits into 10 different buckets by deciding the first frozen digit in a parallelized outer loop.²

src/lib.rs:

use rayon::prelude::*;
// ...
let mut res: Vec<_> = (0..(10 as Number))
    .into_par_iter()
    .flat_map(|i| {
        (0..(10 as Number).pow(NUM_FROZEN as u32 - 1))
            .flat_map(|frozen_number_lower| {
                let frozen_number =
                    frozen_number_lower + i * (10 as Number).pow(NUM_FROZEN as u32 - 1);
                let frozen_digits = num_to_digits(frozen_number);
                disarium_for_digit_count_with_frozen(
                    digit_count_unfrozen,
                    bound,
                    frozen_digits,
                )
            })
            .collect::<Vec<_>>()
    })
    .collect();
res.sort();
res

Using the wonderful rayon library made this code trivial to write. Because of the nondeterministic order introduced by multithreading, I also sorted the result Vec to make the output look nice.³

Optimizing digit-freezing amounts

When I initially implemented digit freezing, I chose $𝑚$,the number of digits to freeze, arbitrarily. Increasing $𝑚$ would eventually converge to just checking each number slowly, and decreasing $𝑚$ would also converge to just checking all numbers, so I knew that the approach needed to be somewhere in the middle. Thus, I decided to benchmark what value of $𝑚$ was fastest for each digit count, hoping to find some kind of pattern.

Previously, NUM_FROZEN had been a constant. I decided to preserve this behavior by using Rust’s const generics to create an array of different variants of the freeze_and_split functions, each with different constant NUM_FROZEN sizes, allowing the frozen digits array to be perfectly sized for all variants of the function.⁴

src/lib.rs:

fn freeze_and_split<const NUM_FROZEN: usize>(digit_count: u32, bound: Number) -> Vec<Number> { 
fn freeze_and_split(digit_count: u32, bound: Number) -> Vec<Number> { 
    // ...
}
// ...
pub const FREEZE_AND_SPLIT_VARIANTS: [fn(u32, Number) -> Vec<Number>; 18] = [
    freeze_and_split::<2>,
    freeze_and_split::<3>,
    freeze_and_split::<4>,
    freeze_and_split::<5>,
    freeze_and_split::<6>,
    // ...
];

Then, I wrote some code to manually benchmark each of these variants, improperly writing my own warm-up code instead of using criterion because I just wanted to see if I could find any patterns in what NUM_FROZEN value resulted in the fastest performance.

src/main.rs:

fn time_digit_count(digit_count: u32) {
    let max = (10 as u128).pow(digit_count) - 1;
    println!("warming up...");
    let start = Instant::now();
    for _ in 0..1000 {
        FREEZE_AND_SPLIT_VARIANTS[5](digit_count, max);
    }
    let duration = start.elapsed();
    println!("warm up for: {}", duration.as_nanos());
    println!("testing digit count: {}", digit_count);
    for i in (0..FREEZE_AND_SPLIT_VARIANTS.len()) {
        let variant = FREEZE_AND_SPLIT_VARIANTS[i];
        let start = Instant::now();
        for _ in 0..100 {
            variant(digit_count, max);
        }
        let duration = start.elapsed();
        println!(
            "duration of variant {i} (number {}): {} nanosecs",
            i + 2,
            duration.as_nanos()
        );
    }
}

After manually trying digit counts 1 to 15, I found that beyond very low digit counts, the best NUM_FROZEN value seemed to consistently be

The differences in times consistently stayed above 2 or 3x slower for increasing or decreasing the NUM_FROZEN value by 1, whittling away doubts about my improper benchmarking methods and giving me reasonable confidence in this pattern.

Using my knowledge, I created an array indexed by digit_count of freeze_and_split functions with optimal FROZEN_DIGITs.

src/lib.rs:

const FREEZE_AND_SPLIT_FUNCS: [fn(u32, Number) -> Vec<Number>; 26] = [
    // ... (low digit counts)
    freeze_and_split::<2>,  // 6
    freeze_and_split::<2>,  // 7
    freeze_and_split::<3>,  // 8
    freeze_and_split::<3>,  // 9
    freeze_and_split::<4>,  // 10
    freeze_and_split::<4>,  // 11
    freeze_and_split::<5>,  // 12
    freeze_and_split::<5>,  // 13
    freeze_and_split::<6>,  // 14
    freeze_and_split::<6>,  // 15
    freeze_and_split::<7>,  // 16
    freeze_and_split::<7>,  // 17
    // ...
]

A reasonable next step would be to find a mathematical explanation for this pattern. I did not do this because that would be hard.

Other optimizations

Besides these important speed-ups, I also fiddled around with smaller optimizations that improved speed slighly, such as

• making all digit_count inputs const generics, to allow for perfectly-sized arrays at compile time
• improving the digit to integer algorithm by copying ideas from itoa
• turning off parallel processing for smaller digit_counts to reduce unecessary overhead
• minimizing integer-to-digit and digit-to-integer conversions

Results

The program can check all u64s in 12423617458 ns, or 12423 ms, or 12 secs! Here’s the terminal output:

0
1
2
3
4
5
6
7
8
9
89
135
175
518
598
1306
1676
2427
2646798
12157692622039623539
found numbers in 12423617458 ns, or 12423 ms, or 12 secs

I’ve also run the program on u128s, checking up to an upper bound of 9999999999999999999999 to check all numbers up to 22 digits if you want to be really sure, achieving a much more tragic time of 377064379625 ns, or 377064 ms, or 377 secs.

This project helped me learn about the importance of

• benchmarking: many optimizations that I was sure would lead to speedups made no difference or made the program slower
• just looking at a dataset and using your brain to try and find patterns

The code, with somewhat reasonable commit messages, lives on Github.

Typst’s HTML export is currently under active development. The feature is still very incomplete and only available for experimentation behind a feature flag. Do not use this feature for production use cases.

Seems like a great time to create a blog that relies on Typst HTML export!

Introduction

This article acts as a guide to building a bare-bones blog website with SvelteKit and Typst, based on my experience making the website you’re currently looking at, with support for code blocks, math, footnotes, and other rich content. I focus on getting the website to function, omitting the styling that makes it look nice.

Because of the experimental nature of Typst’s HTML export, much of this article consists of code that patches unsupported elements into Typst and SvelteKit. If you have a popular blog with billions of important serious users, I probably can’t safely recommend this setup. However, if you really like Typst, really like Svelte, and don’t really mind an unstable setup for your website, this guide is for you.

Why

Because SvelteKit and Typst are both very good.

SvelteKit is built on Svelte, a JavaScript framework that’s extremely simple and focused on developer experience. It also supports static site generation with adapter-static, prerendering each page at compile time for blazingly fast loading speeds on any static website hosting service, such as GitHub pages.

Typst has beautiful markdown-inspired syntax that makes reading the source almost as easy as reading the output. The biggest reason Typst is better than Markdown for a blog is that it is also a fully-featured programming language, allowing you to run arbitrary code to generate your markup.¹

Setup

To generate a SvelteKit project named sveltekit-typst-blog, open your terminal and run

npx sv create sveltekit-typst-blog

Then, when prompted, choose SvelteKit minimal as your template, add TypeScript type checking, and don’t add anything else to your project.² Now, run

cd sveltkit-typst-blog
npm run dev -- --open

You should see your website running in your browser!

Strategy

I’ll discuss the strategy we’ll use to render Typst in our website. We will

1. Write our blog posts in Typst.
2. Use the Typst compiler to convert all Typst files into HTML files.
3. Parse the HTML files server-side to extract metadata, like the post title and publish date.
4. Render the HTML on the frontend with the Svelte @html template syntax.

Posts folder

We’ll start by creating a folder to hold our blog posts. Create a folder src/posts. Inside this folder, create

1. a folder named lib with a file lib.typ, which we will use to create shared code for all articles
2. a folder named target which will contain the generated HTML
3. a file test.typ that we’ll use to test different content types

lib.typ article function

In our lib.typ file, we’ll create a function called article that we’ll wrap all future articles in using show rules:

src/posts/lib/lib.typ:

#let article(
  content,
  title: "Article title",
  date: datetime(year: 2025, month: 12, day: 14),
) = {
  html.elem("html")[
    #html.elem("head")[
      #html.elem("title")[#title]
      #html.elem("meta", attrs: (property: "article:published_time", content: date.display()))
    ]
    #html.elem("body")[
      #content
    ]
  ]
}

Here, we allow users to specify we use Typst’s HTML elem function to generate the basic structure of our document, including metadata in the head element.³

test.typ content types

Now, we can use our newly-created article function in our test article:

src/posts/test.typ:

#import "lib/lib.typ": *

#show: article.with(
  title: "Test article",
  date: datetime(year: 2025, month: 12, day: 14),
)

We’ll also include examples of different types content we want to support in our blog.

src/posts/test.typ:

// ...
= Paragraph
#lorem(67)

= Marks

Marks:

- *bold text*
- _italic text_
- #underline[underline text]
- `code text`
- #link("https://www.google.com/")[link to google]

= Headings

== Heading 2

=== Heading 3

==== Heading 4

===== Heading 5

= Lists

== Unordered
- unordered list
  - that goes
    - like this
- and also has item
- hello

== Ordered
+ ordered list
+ that goes
+ like this
  + and has
    + nestings

= Code

```python
import math

def code_block(with_syntax_highlight):
print("hello world")
x = {"hello": (1, 2), "goodbye": (3, 4)}
return f"hello {1}"
```

= Blockquote

#quote(block: true)[
  Blockquote that is pretty long and contains *rich content*.

  And can be multiline.
]

= Math

Inline math $(1 + 3 + 3^4 / 1) / 2 x y z$ wow that was cool math.

Block math:
$
  cases(1 + 1, hat(2 + 2), 3 + 3/2)
$

Compile to HTML

Now, we can compile our file to HTML! Install the Typst compiler if you haven’t already, then open your terminal and run

typst compile src/posts/test.typ src/posts/target/test.html --format html --features html

You should see a newly created test.html in src/posts/target/test.html! Ignore any warnings you get for now, we will fix them later.

Post rendering

Now, let’s display our posts in SvelteKit!

Extraction functions

First, we’ll create some utility functions to extract the metadata and content out of our generated HTML files. To parse our HTML on the server, which doesn’t have access to the browser’s DOM API, we need to install linkedom. To do that, run

npm i linkedom

Now, create a new file posts.ts in src/lib for our extraction functions. We’ll first create a PostMeta type to group each post’s metadata:

src/lib/posts.ts:

export type PostMeta = {
  title: string;
  date: string;
};

Then, we’ll create a function to extract that metadata, using the parseHTML function from linkedom.

src/lib/posts.ts:

export function extractMeta(html: string): PostMeta {
  const { document } = parseHTML(html);

  const title = document.title ?? "no title";

  const dateMeta = document.querySelector(
    'meta[property="article:published_time"]'
  );
  const date = dateMeta?.getAttribute("content") ?? "2000-1-1";

  return {
    title,
    date,
  };
}

Finally, we’ll create a symmetrical function to extract the article’s content.

src/lib/posts.ts:

export function extractContent(html: string): string {
  const { document } = parseHTML(html);
  return document.body.innerHTML;
}

Post listing

We’ll make the website’s homepage display a list of links to all blog posts. In src/routes, create a new file +page.server.ts. This file will load all HTML files in our target directory and extract the metadata from each one.

src/routes/+page.server.ts:

import { extractMeta } from "$lib/posts";

export async function load() {
  const allPostFiles = import.meta.glob("/src/posts/target/*.html", {
    query: "?raw",
    import: "default",
  });
  const posts = await Promise.all(
    Object.entries(allPostFiles).map(async ([path, resolver]) => {
      const html = (await resolver()) as string;

      const slug = path.split("/").pop()?.replace(".html", "") ?? "unknown";

      return {
        meta: extractMeta(html),
        path: slug,
      };
    })
  );

  return { posts };
}

Then, we’ll edit the existing src/routes/+page.svelte to display a list of links to all posts.

src/routes/+page.svelte:

<script lang="ts">
  let { data } = $props();
</script>

<h1>Posts</h1>
<ul>
  {#each data.posts as post}
    <li>
      <a href="./{post.path}">
        {post.meta.title} - {post.meta.date}
      </a>
    </li>
  {/each}
</ul>

Post display

In src/routes, create a folder called [slug]. Inside that folder, first create a file +page.server.ts. This file will get our HTML file, extract the metadata, and send both the metadata and the article contents to the frontend.

We’ll define a function called load, whose return value SvelteKit will automatically pass to the frontend.

src/routes/[slug]/+page.server.ts:

import { extractContent, extractMeta } from "$lib/posts";
import { error } from "@sveltejs/kit";

export async function load({ params }) {
  const slug = params.slug;

  const module = await import(`../../posts/target/${slug}.html?raw`);
  const html = module.default;

  if (!html) {
    throw error(404, "Post not found");
  }

  return {
    content: extractContent(html),
    meta: extractMeta(html),
  };
}

Here, we first load the HTML by importing it from the target directory based on the URL’s slug (the slug is the part after the last / in the URL, which should match the name of our file, see the SvelteKit routing docs for more information). Then, we use our extraction functions to return the post’s content and metadata.

With all the data we need extracted, rendering it becomes quite easy. Create another file +page.svelte in our [slug] folder. In that file, we’ll write some simple rendering code:

src/routes/[slug]/+page.svelte:

<script lang="ts">
  let { data } = $props();
</script>

<h1>Title: {data.meta.title}</h1>
<p>Published on {data.meta.date}</p>
<article>
  {@html data.content}
</article>

Now, all the pieces are in place! Run npm run dev, and go to localhost:????/test to view the rendered test.typ blog post!

Developer experience

Although the current setup works, the developer experience is not good. Currently, to see changes in your blog post, you have to manually rerun typst compile and reload the website. We’ll fix this by automatically recompiling Typst files when they change, and automatically reloading the website when the source HTML files change in dev mode.

File watcher

First, to install the libraries we need for our file watcher, run

npm install --save @types/node
npm i -D chokidar
npm i -D concurrently

Then, create a new file scripts/typst-manager.ts. This script has two modes, dev and build, corresponding to vite dev and vite build.

• in build mode, it just runs typst compile for all .typ files in src/posts

• in dev mode, it builds all .typ files and checks for updates to .typ files

  • if a .typ file is modified, then the script runs typst watch for that file, which will instantly update the HTML whenever the Typst content changes. The approach prevents spawning hundreds of typst watch processes if you have hundreds of .typ files (assuming that you will likely only edit one blog post at a time).

I won’t go into much more detail about the script. Here’s the code:

scripts/typst-manager.ts:

import { spawn, execSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import chokidar from "chokidar";

const ROOT = process.cwd();
const SOURCE_DIR = "src/posts";
const TARGET_DIR = "src/posts/target";
const EXCLUDE = ["lib.typ"];
const ABS_TARGET = path.resolve(ROOT, TARGET_DIR);

if (!fs.existsSync(path.join(ROOT, TARGET_DIR))) {
  fs.mkdirSync(path.join(ROOT, TARGET_DIR), { recursive: true });
}

const activeWatchers = new Map();

const mode = process.argv[2] || "build";

if (mode === "build") {
  buildAll();
} else if (mode === "dev") {
  buildAll();
  startDevMode();
}

function getTypstFiles() {
  const dir = path.join(ROOT, SOURCE_DIR);
  return fs
    .readdirSync(dir)
    .filter((f) => f.endsWith(".typ") && !EXCLUDE.includes(f));
}

function compileFile(fileName: string) {
  const source = path.join(SOURCE_DIR, fileName);
  const target = path.join(TARGET_DIR, fileName.replace(".typ", ".html"));

  try {
    execSync(
      `typst compile "${source}" "${target}" --format html --features html`,
      { stdio: "inherit" }
    );
    console.log(`built ${fileName}`);
  } catch (e) {
    console.error(`failed to build ${fileName}`);
  }
}

function buildAll() {
  console.log("\nstarting full typst build...");
  const files = getTypstFiles();
  files.forEach(compileFile);
  console.log("build complete.\n");
}

function startDevMode() {
  console.log("watching for changes...");

  const watcher = chokidar.watch(SOURCE_DIR, {
    persistent: true,
    ignoreInitial: true,
    ignored: [ABS_TARGET],
  });

  watcher.on("all", (event, filePath) => {
    const fileName = path.basename(filePath);
    const ext = path.extname(filePath).toLowerCase();

    if (!filePath.endsWith(".typ") || EXCLUDE.includes(fileName)) {
      return;
    }

    if (activeWatchers.has(fileName)) {
      return;
    }

    if (event === "change" || event === "add") {
      spawnDedicatedWatcher(fileName);
    }
  });

  process.on("SIGINT", () => {
    console.log("\nstopping all typst watchers...");
    activeWatchers.forEach((child, name) => {
      child.kill();
    });
    process.exit();
  });
}

function spawnDedicatedWatcher(fileName: string) {
  console.log(`spawning dedicated watcher for: ${fileName}`);

  const source = path.join(SOURCE_DIR, fileName);
  const target = path.join(TARGET_DIR, fileName.replace(".typ", ".html"));

  const child = spawn(
    "typst",
    ["watch", source, target, "--format", "html", "--features", "html"],
    {
      stdio: "inherit",
      shell: true,
    }
  );

  activeWatchers.set(fileName, child);

  child.on("close", () => {
    activeWatchers.delete(fileName);
  });
}

Now, we’ll modify our package.json to run typst-manager.ts whenever we run dev or build. Modify the scripts section of package.json:

package.json:

{
  ...
  "scripts": {
    "typst:dev": "node scripts/typst-manager.ts dev", 
    "typst:build": "node scripts/typst-manager.ts build", 

    "dev": "vite dev",
    "dev": "concurrently \"npm run typst:dev\" \"vite dev\"", 
    "build": "vite build", 
    "build": "npm run typst:build && vite build", 
    ...
  },
  ...
}

Now, if you run npm run dev, any changes to test.typ should be reflected in test.html on save.

Hot reloading

Even though our HTML files change in sync with our Typst files, we have to manually reload our blog in dev mode if we want to see how those changes will look on our website. Let’s fix that!

In vite.config.ts, we’ll create a new custom plugin that notifies the frontend whenever HTML files change.

vite.config.ts:

export default defineConfig({
	plugins: [sveltekit()] 
  plugins: [
    sveltekit(),
    {
      name: "watch-content",
      handleHotUpdate({ file, server }) {
        if (file.endsWith(".html")) {
          server.ws.send({ type: "custom", event: "content-update" });
        }
      },
    },
  ],
});

We can listen for these changes on the frontend by modifying src/routes/+layout.svelte. Add the following snippet to the script section of your +layout.svelte file:

src/routes/+layout.svelte:

import { invalidateAll } from "$app/navigation";
if (import.meta.hot) {
   import.meta.hot.on("content-update", () => {
     invalidateAll();
   });
}

Now, when you’re running npm run dev, any changes to test.typ should be reflected in your browser on save!

Math

Clever observers might have noticed that Typst has been furiously emitting warnings about our use of math blocks in our test.typ file. Even cleverer observers might have noticed that our output HTML currently contains no math—Typst currently removes math elements because it doesn’t know how to display them. Let’s fix this!

In the article function, we’ll create a show rule that changes the way Typst renders math equations:

src/posts/lib/lib.typ:

#let article(
  // ...
) = context {
  show math.equation: it => {
    show: if it.block {
      it => html.elem("div", attrs: (class: "math"), it)
    } else {
      it => html.elem("span", attrs: (class: "math"), it)
    }
    html.frame(it)
  }
  // ...
}

Our show rule maps block math in divs and inline math in spans. Most importantly, it wraps the whole element in a frame, which makes Typst render the contained content as an SVG. Typst doesn’t currently have built-in HTML rendering for math, but it can render any part of the document as SVG, so we just wrap all our math equations with frames to show them as SVGs instead.⁴

Now, math displays correctly!

Footnotes

Let’s add support for footnotes!⁵ We want numbered superscripts that link to numbered footnotes at the bottom of the article which all also have backlinks. First, create another show rule:

src/posts/lib/lib.typ:

#let article(
  // ...
) = context {
  show footnote: it => {
    let count = counter(footnote).display()
    super([#{
        show html.elem.where(tag: "a"): it => {
          if it.attrs.at("role", default: none) == none {
            html.elem("a", attrs: (..it.attrs, role: "doc-noteref", aria-label: "footnote " + count), it.body)
          } else {
            it
          }
        }
        link(label("footnote-" + count), count)
      } #label("footnote-return-" + count)])
  }
  // ...
}

This show rule uses Typst’s counter function to display numbered footnotes linked to their sources, and also sets up backlink targets so that readers can return to the article after reading the footnote. We use a show rule to add accessible attributes to the generated a element.

Then, let’s update the html.body function to display each footnote, using Typst’s query function to find each footnote’s content.

src/posts/lib/lib.typ:

#html.elem("body")[
  #content
  #context {
    let footnotes = query(footnote)
    if footnotes.len() != 0 {
      html.elem("footer")[
        #html.elem("ol")[
          #for (i, footnote) in footnotes.enumerate() {
            let count = str(i + 1)
            [#html.elem("li", attrs: (role: "doc-footnote"))[
                #footnote.body #{
                  show html.elem.where(tag: "a"): it => {
                    if it.attrs.at("role", default: none) == none {
                      html.elem(
                        "a",
                        attrs: (
                          ..it.attrs,
                          role: "doc-backlink",
                          aria-label: "Back to content",
                        ),
                        it.body,
                      )
                    } else {
                      it
                    }
                  }
                  link(label("footnote-return-" + count))[↩︎]
                }] #label("footnote-" + count)]
          }
        ]
      ]
    }
  }
]

Here, we create the targets for the links we set up in our show rule, and create backlinks with the ↩︎ symbol at the end of each footnote. We also use another show rule to add accessible attributes to our links.

We can our implementation by modifying our test.typ file to include some example footnotes:

src/posts/test.typ:

// ...
= Footnote

Let's make footnotes#footnote[An example footnote]
and more footnotes#footnote[
  Another example footnote with *rich content*
]

Now, we have support for footnotes!

Conclusion

I hope this article provided a good guide for the basics of setting up a SvelteKit + Typst blog. Other features, like support for arbitrary figures or images that aren’t just embedded into the HTML can be implemented pretty easily with more show rules and some extra JavaScript. You can find the code on Github.

The approach I used has good developer experience but is somewhat fragile; future solutions could use typst.ts to make a proper Vite plugin.

Paragraph and marks

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim aeque doleamus animo, cum corpore dolemus, fieri tamen permagna accessio potest, si aliquod aeternum et infinitum impendere malum nobis opinemur. Quod idem licet transferre in voluptatem, ut postea variari voluptas distinguique possit, augeri amplificarique non possit. At etiam Athenis, ut e patre audiebam facete.

Footnote that shows up¹, and then after that, another interesting² group³ of footnotes⁴.

Marks:

• bold text
• italic text
• underline text
• code text
• link to google

Headings

Heading 2

Heading 3

Heading 4

Heading 5

Duplicate heading

Duplicate heading

Rich heading with strange print("rich content")

Lists

Unordered

• unordered list

  • that goes

    • like this
• and also has item
• hello

Ordered

1. ordered list
2. that goes

3. like this

   1. and has

      1. nesings

Code

Inline code like print("hello world") is very beautiful.

raw text
wow raw text is so good

look at this raw text

import math
def code_block(with_syntax_highlight):
	print("hello world")
	x = {"hello": (1, 2), "goodbye": (3, 4)}
	return f"hello {1}"

Ansi

* 366a8c3 (HEAD -> main, origin/main) add toc
* 10075bd add shiki transformers
* 482914a marginally improve syntax highlighting with shiki

File display

hello-world.py:

print("hello world")
for i in range(0, 10):
  print(i)

src/main/long/path/that/is/very/long/and/extremely/long/hello-world.py:

print("hello world")
for i in range(0, 10):
  print(i)

Annotations

console.log("remove"); 
console.log("normal");
console.log("add"); 
console.log("normal");
console.log("highlight"); 
console.log("normal");
console.error("error"); 
console.log("normal");
console.warn("warning"); 
console.log("normal");
let x = [1, 2, 3, (4 + 5)]; 

function helloWorld() {
  console.log("not important");
  console.log("focused"); 
  console.log("not important");
}

Table

Blockquote

Blockquote that is pretty long and contains rich content.

And can be multiline.

Math

Inline math $\frac{1+3+\frac{3^4}{1}}{2}𝑥𝑦𝑧$ wow that was cool math.

Block math:

Embedded components

Lorem
ipsum
dolor
sit
amet,
consectetur
adipiscing
elit,
sed
do
eiusmod
tempor
incididunt
ut
labore
et
dolore
magnam
aliquam
quaerat
voluptatem.
Ut
enim
aeque
doleamus
animo,
cum
corpore
dolemus,
fieri
tamen
permagna
accessio
potest,
si
aliquod
aeternum
et
infinitum
impendere
malum
nobis
opinemur.
Quod
idem
licet
transferre
in
voluptatem,
ut.

Images

Figure

Ending paragraph

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim aeque doleamus animo, cum corpore dolemus, fieri tamen permagna accessio potest, si aliquod aeternum et infinitum impendere malum nobis opinemur. Quod idem licet transferre in voluptatem, ut postea variari voluptas distinguique possit, augeri amplificarique.