New Blog Who Dis

2026-08-29

So recently I discovered Typst (I’ve been behind the times) and started using it at work for generating some PDFs. Previously I had been using Asciidoc and while I think Asciidoc is awesome, it’s not as extendable as Typst and you also need Ruby. Typst being a single binary and also having a great online platform are great benefits and I’ve really enjoyed using it.

I was reading the blog post on the new Hypermedia Systems book and noticed that Shiroa was mentioned. I realize that its main purpose is for books, but I wanted to see if I could use it as more of a blog platform.

The old site was built with Hugo and I had a mix of Markdown and Asciidoc files to generate the pages. Customizing things always came down to modifying CSS or partials which I always found slightly annoying. With Typst, I can extend things much more easily through the language itself instead of creating custom partials, shortcodes, or CSS.

The initial setup was pretty easy with shiroa initshiroa init and I was able to pretty easily move all the old posts to chapterschapters in Shiroa.

Each post is its own file, which ends up being imported as a chapter. I created an array of dictionaries to describe each file (path, name, and date) and then I can build the summary of chapters from that array. Building the main page is just ranging over the first 5 itmes in that array and creating links from them.

#let posts = (
  (
    link: "posts/new-blog.typ",
    name: "New Blog Who Dis",
    date: "2026-08-29",
  ),
  (
    link: "posts/realtime-config.typ",
    name: "Real Time Configs with NATS",
    date: "2025-11-05",
  ),
  ...

#let posts = (
  (
    link: "posts/new-blog.typ",
    name: "New Blog Who Dis",
    date: "2026-08-29",
  ),
  (
    link: "posts/realtime-config.typ",
    name: "Real Time Configs with NATS",
    date: "2025-11-05",
  ),
  ...

summary: {
  let result = [- #prefix-chapter("hello.typ")[Hello]]
  result += [= Posts]
  for post in posts {
    result += prefix-chapter(post.link)[#post.name]
  }
  result
}

summary: {
  let result = [- #prefix-chapter("hello.typ")[Hello]]
  result += [= Posts]
  for post in posts {
    result += prefix-chapter(post.link)[#post.name]
  }
  result
}

Not everything is perfect and that’s mainly due to a few factors.

• The fact I’m using a web book platform for a blog
• The fact that HTML exporting from Typst is still experimental
• The fact that Shiroa is still really new

I’m exporting the site with --mode=static-html--mode=static-html which works well, however some things will not export correctly (or at all).

For example I have a custom function to create code blocks that contain callouts.

Creating a codeblock with that function looks like this

#codeblock(
  title: "Codeblock Title",
  callouts: (
    [This line does something],
  )
)[
```lang
do something [1]
```
]

#codeblock(
  title: "Codeblock Title",
  callouts: (
    [This line does something],
  )
)[
```lang
do something [1]
```
]

which renders like this

do something [1]

do something [1]

When using this function in PDF generation the styling sets the title and callouts to italicized with a light gray color. However exporting to static HTML does not keep this styling. Running shiroa buildshiroa build without that mode will preserve that styling but I’ve found things like site search not working in that mode. This isn’t a big deal and something I’m willing to deal with, but wanted to call this out in case you decided to try this as well.

I’ve also noticed some things wont render at all. For instance I have a d2 diagram in another post and exporting to static HTML will show the diagram, however if I wrap the diagram in an #align#align, the diagram will not show up like in the following:

#align(center)[
  #render(
    "
    a -> b
    ",
    engine: "elk",
  )
]  

#align(center)[
  #render(
    "
    a -> b
    ",
    engine: "elk",
  )
]  

Instead of adding the date manually to each post then, I can use this helper to inject the dates into each page from the single array. I could just add the date to each page, but then I would need some other way to add it to the list of most recent posts.

#let post-page(link: none, title: "", authors: (), body) = {
  let post = posts.find(p => p.link == link)
  let date = if post != none { post.date } else { none }
  show: book-page.with(title: title, authors: authors, date: date)
  body
}

#let post-page(link: none, title: "", authors: (), body) = {
  let post = posts.find(p => p.link == link)
  let date = if post != none { post.date } else { none }
  show: book-page.with(title: title, authors: authors, date: date)
  body
}

I’m using the release candidate right now for Shiroa. One thing I’ve noticed with this is that you cannot remove the Discord social link. It’s due to how the social links are exposed through the Starlight theme. I don’t really use Discord and have no reason to link it so I did add some custom CSS to just hide the Discord social icon. I know I said above that was one reason I left Hugo, but this was a minimal change.

From what I can tell, there is no way to use a different icon for the repository link right now, so while I have a GitHub, I mainly use GitLab and I just linked my GitLab even though the icon shows as GitHub.

I’ve been really happy with this so far. I get to write in Typst for blog posts which to me just feels more fun than writing Markdown and even Asciidoc. It’s not perfect, but that’s really due to me using a platform early on and in a way it was not intended to be used.