From Zola

The closest neighbour: one Rust binary, a content tree, a template directory, taxonomies and pagination in the config. The posts stay markdown, since a .md file under content/ is a page (Markdown pages), and a +++ block is TOML here exactly as it is there, so a post copies over as it stands. What has to change is a handful of frontmatter key names, the shortcodes, the internal links and the config; the templates are a rewrite.

The tree

The config

Tables, footnotes, strikethrough and tasklists are on without asking, and the list adds rather than replaces, so extensions "smart" keeps all four and turns typographic quotes on. -name drops a default. The full list is in the reference under content.markdown.extensions.

A Zola section carries its own settings in _index.md. Here they are a collection block:

content {
  collections {
    blog {
      sort "date"
      reverse #true
      template "page.typ"
      paginate { size 10; template "list.typ" }
    }
  }
}

description carries over under its own name, and fills the feed channel the same way Zola’s does.

Frontmatter

The language needs no conversion: +++ is TOML here too, and a block copies over character for character (Markdown pages has all three fences). TOML’s date literal comes with it, so date = 2026-07-09 is read as the ISO day it spells, unquoted, exactly as Zola reads it.

What changes is the names of two keys, and where two of Zola’s tables put their contents:

+++
title = "Hello"
date = 2026-07-09
order = 3                    # was weight
redirect = ["/old/hello/"]   # was aliases
tags = ["rust", "cli"]       # was under [taxonomies]
hero = "cover.png"           # was under [extra]
+++

A taxonomy has to be flat: tags is looked up at the top level and nowhere else, so a [taxonomies] table left in place joins no term. [extra] is a choice - it survives as a dict, so a template can read page.frontmatter.extra.hero instead of flattening it. Flattening is what makes the key look like every other one.

A post you convert to .typ writes the same fields as a Typst dict instead:

#let frontmatter = (
  title: "Hello",
  date: "2026-07-09",
  order: 3,
  redirect: ("/old/hello/",),
  tags: ("rust", "cli"),
  hero: "cover.png",
)

There a list of one needs the trailing comma - ("rust") is a string, ("rust",) is a list - which is the one thing TOML’s ["rust"] never made you think about.

Templates

Tera inheritance becomes ordinary imports. A base template is a function you call around your body, not a file you extend:

<!-- templates/page.html -->
{% extends "base.html" %}
{% block content %}
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
{% endblock %}

// templates/page.typ
#import "@baudelaire/html:0.1.0": h
#import "/templates/base.typ": shell

#let page(page, body) = shell(page)[
  #h("h1", page.frontmatter.title)
  #body
]

That last row is deliberate. Nothing site-wide may enter a page’s wrapper, or every page’s cache identity would depend on every other page. Templates reach the site through @baudelaire/sections and @baudelaire/pages instead, which are tracked as files. See templates.

Template names are yours: there is no page.html / section.html / taxonomy_single.html convention, only the template you bind on a collection, a taxonomy, or a page.

Shortcodes

Nothing interprets {{ .. }} or {% .. %} in a page. In markdown they are prose, so a shortcode you forget ships to the reader as the braces you wrote and no build fails. Grep the tree for them before you call the migration done.

A shortcode becomes a function in a file you import:

// templates/parts.typ
#let youtube(id) = html.elem("iframe", attrs: (
  src: "https://www.youtube-nocookie.com/embed/" + id,
  loading: "lazy",
  allowfullscreen: "true",
))

A markdown page calls it from a fence marked eval, which is the one place a .md page runs Typst:

```typ eval
#import "/templates/parts.typ": youtube
#youtube("dQw4w9WgXcQ")
```

A converted page calls it as #youtube("dQw4w9WgXcQ") in the body. Body shortcodes ({% quote() %} .. {% end %}) take the body as a content argument: #let quote(body) = .., called as #quote[..]. Most shortcodes only wrapped a tag or two and are not worth a function at all: write the markup.

Internal links

A link names the source file, .md or .typ, and the build rewrites it to that page’s permalink. @/blog/hello.md is Zola’s spelling of the same idea and means nothing here - but it no longer slips through either, since @ is not a directory and the target does not resolve:

× `@/blog/other.md` has no matching page
  ╭─[blog/hello.md:7:16]
7 │ A post. [zola](@/blog/other.md)
  ·                ───────┬───────
  ·                       ╰── no page here

So the @/ links are a mechanical fix the build finds for you, one page at a time. Old absolute URLs are the ones nothing checks: they survive a copy and break on the first rename, which keeping your URLs is about. See pages.

Raw HTML

Zola passes raw HTML in a post straight through. Here it fails the build, on the line it sits on: the DOM this build produces is typed, and there is nowhere to splice a string of markup into it. Three answers:

An HTML comment is dropped either way: it has nothing to lose.

What Zola wrote that this does not

Commands

Order of work

1. baudelaire init beside the old site, then copy static/ across and move sass/ into assets/. The .scss files are compiled where they lie and published as .css; partials keep their leading _ and are published by nobody.
2. Copy content/ across as it stands, +++ blocks included, and delete the _index.md files.
3. Rename the frontmatter keys that moved: weight to order, aliases to redirect, and lift [taxonomies] to the top level. Nothing fails if you miss one, so this is a grep over the tree, not a build.
4. Port config.toml to config.kdl, one block at a time. An unknown key fails the build with a suggestion, so this converges fast.
5. Rewrite the templates one section needs. Everything else can stay unstyled while you work.
6. Strip the @/ from the internal links - the build names them - then replace the shortcodes and convert the pages that actually want Typst.
7. baudelaire check until it is quiet, then compare sitemaps as in keeping your URLs.