Why does my simple counter trigger "layout did not converge"?

Questions
,
1

I’m writing lecture notes and I have little markers on the side that indicate where each lecture started. This is how I implemented them:

#let vlcount = counter("vorlesung")
#let vlstart() = {
  vlcount.step()
  sidenote[VL#context[#vlcount.display()]]
}

Then each time a lecture starts I just use vlstart() and it worked fine for 19 lectures and 90 pages. Once I put the 20th of these, I get the warning that layout did not converge within 5 attempts. I read the manual page about state but I don’t understand what’s wrong. It’s just stepping a counter and displaying the state with no time travel or anything.

The layout does succeeds, is fast and outputs the intended sidenotes. I have no problems except the warning.

How should I implement this to don’t get into layout loops?

Edit: Weird observation: Removing the last #vlstart() in my document makes the warning go away. Removing one or more of the other ones does not make the warning go away. So maybe it is a combination of that counter with the rest of the document after all?

1 Like
2

Due the lack of information, I can’t solve your mystery; but perhaps you can help yourself with layout-ltd – Typst Universe. This package allow you to inspect each layout iteration.

#import "@preview/layout-ltd:0.1.0": layout-limiter
#show: layout-limiter.with(max-iterations: 2)
2 Likes
3

Using this I can see that with max-iterations:3 each counter displays “VL20” with max-iterations:4 they look correct but the last one is missing, with max-iterations:5 they are all correct. So it seems something about the construction of the counter and placement of sidenotes.

I tried to make a minimal non-working example, but a document that looks like this:

#import "@preview/marge:0.1.0": sidenote, container
#let vlcount = counter("vorlesung")
#let vlstart() = {
  vlcount.step()
  sidenote[VL#context[#vlcount.display()]]
}

#vlstart()
A
[... many times this ...]
#vlstart()
A

compiles just fine without any warning.

4

The step is called outside of the context and display is called inside of the context, so it’s as correct as you can make it.

However, a quick look at the now locatable in marge sidenote shows that it’s somewhat context heavy, so either it by itself or with the combination of yet another custom counter pushes the iteration count over 5. My guess is that sidenote is the problem, and maybe the underlying code can be optimized to not trigger so many iterations.

Also, if your document has some references, it also increases iteration count, AFAIK.

Well, clearly you’ve stripped too much. There should be a middle ground. Which should tell the potential cause. Remove small parts at a time between checks, substituting text with lorem, etc.

5

Inherently, margin notes are very context heavy and performance can depend also on things like “how many notes on a single page” and “how many different pages with notes” etc.

You could try if either of the following help:

  • Use the “container” feature of marge. According to the docs, this may improve performance;
  • or use a different package for the margin notes, i.e. my package marginalia – Typst Universe . The two packages work very differently under the hood, so it might be that one of them works better here.
6

I tried to get a MWE: The following hits a “layout did not converge”:

#import "@preview/marge:0.1.0": sidenote

#let vlcount = counter("vorlesung")
#let vlstart() = {
  vlcount.step()
  sidenote[VL#context[#vlcount.display()]]
}

#lorem(500)
#vlstart()

#lorem(500)
#vlstart()

#lorem(500)
#vlstart()

#lorem(500)
#vlstart()

#lorem(500)
#vlstart()

(Also, the “VL4” which should appear at the bottom of the second-to-last page (page 3) is missing)

It appears that the long paragraphs or unpredictable page breaks are the issue.[1]

Replacing the first line with either of the following solves the convergence:

#import "@preview/marge:0.1.0": sidenote, container
#set page(background: container)

or

#import "@preview/marginalia:0.3.1" as marginalia: note
#show: marginalia.setup.with(
  book: true,
)
#let sidenote = note.with(counter: none)

(The marginalia option places “VL4” at the bottom of page 3, where the corresponding lorem-paragraph ends, the marge-container options places it at the top of page 4 for some reason)

  1. Because of your remark, is supect that in your document, the last ond only the last VL is somehwere where a large paragraph or unpredictable pagebreaks mess up marge’s calculations ↩︎

1 Like
7

If you can manage to recreate an MWE, maybe try it under this PR branch: Detailed non-convergence diagnostics for introspections by laurmaedje · Pull Request #7364 · typst/typst · GitHub. This is not yet released but should give more detailed hints at where the convergence fails.

1 Like
8

(You can download pre-built binaries for main.2025-12-02.dc1a176 from Build typst · typst-community/dev-builds@7d14b2f · GitHub, in case you can’t or don’t want to compile typst from source code.)

1 Like
9

Thanks for these detailed explanations. Yes, it does seem to depend essentially on how the paragraphs look, which contain the margin note. In the case of my 20th note, there is a 3-line paragraph at the bottom of a page. If I put the 20th note in this paragraph, no convergence, neither with container, neither with marginalia package. If I move the note to the next paragraph, it works with my original setup (and all others too).

I don’t understand what’s going on here. There is nothing special in this paragraph or around it.

1 Like
10

If the paragraph is at the bottom of the page, it might be that it takes typst a while to decide which page it is on. Because the margin notes positioning (in both packages) needs to keep track which note is where, every time typst ““changes its mind”” as to where the pagebreaks are, this then changes a lot of states. In some situations like this it might help to manually place some #pagebreak(weak:true) as this makes the whole-document layout more predictable for typst[1][2]

  1. Ive encountered this with an outline which only barely fit onto the page, and placing a pagebreak after it solved it in that case ↩︎

  2. Also, this is just how intuit about this, but it seems to track ↩︎

1 Like
11

Yes, you have solved the mystery, I think. It is related to that paragraph jumping between pages in the layout iterations. The solution with manual page breaks is kind of bad because I can’t know if that paragraph stays there forever. I also occasionally make changes to earlier parts of the document.

My margin notes are really simple. They are just “VL 20”, two letters and a number. Maybe I should just place them 2cm to the left and take them out of the layouting loop?

There must be a clean and easy way to put some progress markers on the side of the document that does not interfere with layout too much.

2 Likes