Typst: cap images with a fixed width at the text width

[faysou]

In Typst output, an image with an explicit size is placed at that size even when it is wider than the text area. LaTeX output behaves the same way.

---
format: typst
---

![Wide](penrose.svg){width=12in}

The .typ keeps #box(image("penrose.svg", width: 12in)) on an 8.5in page, so most of the image runs off the page. Mermaid and Graphviz diagrams hit this often, because Quarto sizes them from their natural size in inches. In LaTeX output the same diagrams produce \includegraphics[width=17.61in,...].

Proposal

Cap image width at the text width, the way HTML output does with max-width: 100%. In Typst, one way to cap the width is to wrap the image in layout(size => ...) and use calc.min(width, size.width), scaling the height by the same factor.

This changes how existing documents with oversized images render, so I'd like agreement before opening a PR:

• Should the cap be the default, or an opt-in option?
• Should LaTeX output get the same cap?

[mcanouil]

I'd lean towards leaving this as it is, and not making the cap the default.

Relative widths already work in Typst. Pandoc's Typst writer passes the width attribute through as written, so {width=100%} becomes image(..., width: 100.0%) and fits the text area, while {width=12in} stays 12in.

• https://github.com/jgm/pandoc/blob/2ddd82c041ca58e2cd10608f92b48ac081328921/src/Text/Pandoc/Writers/Typst.hs#L568-L576

So when someone writes an absolute width, they've asked for that size, and I think Quarto should respect it. A silent cap would also change how existing documents render, and it would make 12in and 100% give the same result with no way to opt out. If the problem is mostly Mermaid and Graphviz diagrams, it might be better to look at how Quarto picks their default size, rather than capping every image.

For anyone who wants auto-shrink today, a Typst show rule does it in a few lines. It only scales images that are wider than their container and leaves the others alone:

---
format:
  typst:
    include-in-header:
      - text: |
          #show image: it => layout(size => {
            let natural = measure(it)
            if natural.width > size.width {
              let r = size.width / natural.width * 100%
              scale(x: r, y: r, reflow: true, it)
            } else { it }
          })
---

The same rule also works from a .typ file passed to include-in-header, or inside a {=typst} raw block at the top of the document. I tested all three with Quarto 99.9.9 (Pandoc 3.10): a 12in image shrinks to the text width, and a 2in image keeps its size.

If the cap does go in, I'd rather see it as an opt-in option for Typst only, and leave LaTeX as it is.