From Hugo

Hugo has the larger feature surface, so this is the migration where you should check what you actually use. The posts themselves copy across as files: a .md file under content/ is a page here too, and its frontmatter block is read in the language its fence already says it is. --- is YAML, +++ is TOML. What has to change is a handful of frontmatter key names, the shortcodes, the internal links and the config. Go templates and render hooks collapse into ordinary Typst functions.

The tree

The config

Hugo infers a section from a directory and layers _index.md, type and cascade on top. Here a directory is a collection, and everything about it is in one block:

content {
  collections {
    posts {
      sort "date"
      reverse #true
      permalink "/{year}/{month}/{slug}/"
      template "page.typ"
      paginate { size 10; template "list.typ" }
    }
  }
}

_root { template "page.typ" } covers the pages directly under content/, which is the closest thing to Hugo’s home and top-level singles.

Goldmark’s defaults and this parser’s are close but not identical. Tables, footnotes, strikethrough and tasklists are on; Hugo’s typographer is not, and is extensions "smart". The full list is in the reference under content.markdown.extensions, where a * marks what you already have.

Frontmatter

The block does not change language. The fence picks it, so a Hugo post’s --- is read as YAML and a +++ as TOML, exactly as Hugo read them. What changes is the spelling of a few keys:

---
title: "Hello"
date: 2026-07-09
lastmod: 2026-08-01
draft: true
weight: 3
aliases: ["/old/hello/", "/older/hello/"]
tags: ["rust", "cli"]
params:
  hero: cover.png
---

becomes

---
title: "Hello"
date: 2026-07-09
updated: 2026-08-01
draft: true
order: 3
redirect: ["/old/hello/", "/older/hello/"]
tags: ["rust", "cli"]
params:
  hero: cover.png
---

A tags key is nothing at all until the taxonomy is declared. Until then it is an unrecognised key like any other, so a copied post publishes with no terms and no complaint. See taxonomies.

The third fence, ;;;, is KDL, the language the config is written in. Nothing about a Hugo migration needs it, and it is the one dialect that cannot spell a one-element list. See Markdown pages.

A collection can require the fields its template reads, which is the checked version of what Hugo leaves to .Params and an empty string. See schemas.

The slug is not the same string

This is the one that quietly rewrites every URL. Hugo’s :slug token falls back to the title, urlized. Baudelaire’s slug comes from the filename.

So a Hugo site whose filenames are short and whose titles are sentences moves every post the moment you copy the permalink pattern across. Either rename the files to the old slugs, or write slug into each page’s frontmatter, before comparing sitemaps. slug in Hugo frontmatter already pinned the URL and carries over unchanged.

Raw HTML

Hugo’s Goldmark passes HTML through once renderer.unsafe is on, and themes lean on it. Here a .md page that contains any is refused, because the DOM a build produces is typed and a string of markup has nowhere to be spliced into it. Three answers, in the order worth trying:

The refusal names the file, the line and the tag, so a tree is worked through by building it. html "drop" is the one to be careful with: an embedded widget is a block-level run, and dropping it drops what it contained.

Shortcodes and render hooks

Both become Typst functions. A shortcode lives in a file the page or template imports:

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

A markdown page reaches it through an eval fence, which is where {{< youtube id >}} used to be:

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

A .typ page calls #youtube("dQw4w9WgXcQ") outright. Either way eval #false turns the fences off for a site that imports content it did not write.

A render hook, which in Hugo rewrites every link or image in the Markdown, is a #show rule in the template that draws the page, so it applies to a .md body the same as a .typ one:

#let page(page, body) = {
  show link: it => h("span", class: "external", it)
  body
}

Internal links

{{< relref "sleepers.md" >}} and {{< ref >}} have no meaning here, and no error either: they are the text above. What they wrapped is what you keep.

[sleepers](sleepers.md)

A plain link naming a source path is resolved against the linking file and rewritten to that page’s permalink, and if no page is there the build fails. Both extensions work and either may name either kind of page, so a .md post linking a converted .typ one needs no thought. That is the mechanism that finds the links a migration broke.

So convert {{< relref >}} to the source path, not to the URL it produced: a URL survives a rename only if the URL does. check { links "warn" } demotes the failure to a warning, which is the setting for working through a large tree. See pages.

Templates

<!-- layouts/_default/single.html -->
{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ partial "byline.html" . }}
  {{ .Content }}
{{ end }}

// templates/page.typ
#import "@baudelaire/html:0.1.0": h
#import "/templates/parts.typ": shell, byline

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

The absent .Permalink is deliberate: nothing site-wide may go into a page’s wrapper, or every page’s cache identity would depend on every other page. The site tree and the page catalogue come from @baudelaire/sections and @baudelaire/pages, which typst tracks as files. See templates.

Page resources

A Hugo page bundle addresses its own files. A bundle here is a directory with an index.md or index.typ in it, and the same files are reached two ways:

The body names it the way Markdown always did:

![Vienna](vienna.png)

The picture publishes at /assets/posts/hello/vienna.png: an extracted image keeps the directories it was authored under, relative to content/, so a tree where every post has its own cover.png does not collide. Only a file the page actually shows is written, so a hero the template draws from page.assets has to be named in the body as well, or it has a URL and no file. See images.

Commands

Order of work

1. baudelaire init beside the old site, then copy static/, assets/ and content/ across.
2. Port the config. An unknown key fails the build with a suggestion, so work down the file until it is quiet.
3. Rename the frontmatter keys in one section, and set its collection’s permalink to whatever permalinks produced before. See keeping your URLs.
4. Grep that section for {{<, {{% and raw HTML: those are what a page cannot carry across silently.
5. Rewrite the templates it needs, starting with the shell.
6. baudelaire check, then compare the old and new sitemaps.