[markbac]

Summary

Wait for Docker to start

On Windows, WSL shuts its VM down when idle. The next build's first Docker call then has to start WSL, systemd and Docker, and Docker restarts any containers set to restart. That took longer than the 60 seconds allowed, and the build failed on its first diagram with a misleading message:

mermaid diagram failed: docker image did not finish within 60 seconds

• The image check, which is the first engine call of a run, now allows 300 seconds (image.STARTUP_TIMEOUT).
• If Docker still does not answer, the error says so and suggests wsl --shutdown on Windows, or restarting Docker on Linux.

[[PAGEBREAK]] directive

Legacy documents use [[PAGEBREAK]], which py-doc passed through as text. A [[PAGEBREAK]] line on its own now becomes a ::: {.pagebreak} block: a page break in Word and PDF, a new slide in a deck, nothing on a site. Inside code it is left as written.

One caption per diagram

A [[CAPTION:Figure]] line next to a diagram gave it two captions, because pandoc also made one from the picture's alt text:

Caption line	Word before	HTML / PDF before	After, every format
none	alt text	alt text	alt text
above	2 captions	1	the line's
below	2 captions	alt-text caption, plus the line as a loose paragraph	the line's

• Word: a diagram with a caption line directly above or below is written so that pandoc does not make it a figure (a no-break space after the picture). [[CAPTION:Table]] lines are not counted, so they still go to their table.
• HTML, PDF and PowerPoint (markers.lua): a caption line below a diagram now captions the figure inside the diagram's centred div.

Picture and diagram widths

• [](a.png){width=50%} now works in Word too. pandoc's Word writer ignores %, so the new widths.lua converts it to cm of the template's text width (page width less margins), which the engine reads from the reference document. With no page set in the template it uses 14.82 cm, the widest pandoc makes a picture then. HTML and PDF already honoured %.
• Diagram fences take width="100%" (or cm, mm, in, px) after the language. Any other value stops the build with the file and line.

Docs and example

The writing guide and examples/ show [[PAGEBREAK]] (03_operations.md), a diagram captioned below, and diagrams at 100% and 60% (02_design.md).

Testing

• New tests: the start-up timeout and its error; [[PAGEBREAK]] expansion and a Word build with one page break; one caption per diagram for none/above/below in Word, HTML and PowerPoint (2 fail on the old code); % widths for a diagram and a picture against a template with a 17 cm text width in Word and HTML; a bad width is an error.
• Full suite passes except tests/test_examples.py, whose 7 failures also occur on main in this environment because Graphviz, Mermaid and PlantUML are not installed here. py-doc lint is clean on examples/docs and docs/guide; ruff check is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ket2UPXgz46XKSUqpuPixk