Why does HTML export emit images as Base64 data URIs instead of keeping the original image links?

Questions
,
1

When exporting a document to HTML, images are emitted as Base64 data: URIs inline in the output instead of keeping a reference to the original image file/link.

I understand this makes the exported HTML self-contained and portable, but it also has some notable downsides: the output grows a lot for documents with many or large images, the browser can no longer cache images separately (nor can they be served from a CDN), and any tooling that would like to post-process the assets has to parse the HTML.

So my questions are:

  • What motivated this design choice? Is the main reason self-containment/portability of a single HTML file?
  • Is there any (current or planned) way to keep images as external references, e.g. writing the image files next to the HTML file and linking them with relative paths, or preserving the original URL for images that came from the web?
  • Are there recommended workarounds today (post-processing the HTML, CSS overrides, etc.)?

Thanks!

2

I think it was originally done this way when an output was always a single file. Now, there is also bundle export, which supports multiple output files, so you can right now get the result you want: use an asset() for the image (or for an SVG created via typst, a document()), and the asset’s path as the url for an html.img tag.

I don’t know whether the HTML default is going to change, or if bundle export will remain the way to output HTML + assets.