Rendering fixes: math-punctuation, fonts, and a render regression test#1309
Merged
Conversation
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
Rendered KaTeX output can linebreak between a math span and following punctutation (KaTeX/KaTeX#1233). This is a very common case in practice. There is also too large a gap between the math and the punctuation. We used to manually put the punctuation inside the math span as a hacky workaround. This has several problems: * it's easy to forget; * it's terrible, presentation-oriented markup; * the punctuation is in the wrong font (math instead of body). A previous attempt at fixing this used `render.sh` to apply the hack automatically. Until recently this was only done for rst; 7629f6a started doing it for Markdown as well. However, * this was fragile because it can break the markup syntax if the punctuation character is not followed immediately by whitespace or end-of-line (e.g. $t$-of-$n$, $k$-byte); * the rewrite could potentially fire on the *opening* `$` of a span whose content starts with punctuation, rather than the closing one as intended; * it still used the wrong font. This commit cleans all of that up. `\textsf` in math now exactly matches the body font (Roboto Regular). The rewrites are not applied when they would break the markup, and more punctuation is handled correctly. This allowed almost all manual applications of the hack to be removed. As a bonus, instances of "and", "if", "otherwise", etc. in math now use `\textsf` and are in the body font. The serif font can still be accessed via `\text`. Note that the rewriting is line-by-line, so a multi-line `$...$` span (which is valid in Markdown) is not matched: punctuation immediately after such a span won't get the spacing or linebreak correction. Also, a line holding both one span's close and another's open can still mismatch. Both cases are rare, surface when reviewing rendered output, and are easy to work around. Punctuation after a $$ span, e.g. `$${xyzzy}$$.`, will not be rewritten. This can be replaced by `$${xyzzy}\textsf{.}$$`. There were some intricacies in making sure that our intended font overrides take precedence over the KaTeX fonts. Previously, `style.css` was loaded after the KaTeX CSS for rst, and before for Markdown, resulting in confusing differences between the two. We use the `!important` sledgehammer on the overrides to make sure, but we also make the load order consistent (`style.css` last) to ease future debugging. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
The `raleway` and `ralewayitalic` @font-face rules point at variable fonts (`...VariableFont_wght.ttf`, wght axis 100–900, default 100) but declared a single `font-weight: normal`. With only one weight declared, browsers disagree on which axis instance to render — Firefox and Chromium differ — so `*Ironwood pool*` (which uses `ralewayitalic`) rendered at different weights. The running-text `em` rule requested `font-weight: 720`, which fell outside the single declared weight and so was unreliable; and math-mode pool names (`.katex .textit`) pinned no weight at all, so they did not match the running-text emphasis. Declare the full `100–900` range on both @font-face rules, then pin emphasis to a consistent medium weight: `em` and `.katex .textit` both use `font-weight: 500`. Emphasis and pool names now render at the same weight in running text and in math, and consistently on Firefox and Chromium. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
nuttycom
reviewed
Jun 24, 2026
| run: nix develop --profile /tmp/dev-profile --command make all-zips | ||
|
|
||
| - name: Render regression tests | ||
| run: nix develop --profile /tmp/dev-profile --command make test |
Contributor
There was a problem hiding this comment.
Is there a missing test target for the Makefile, or was this supposed to make rendered/test?
Collaborator
Author
There was a problem hiding this comment.
make test is correct.
render.sh's math-punctuation rewriting and the stylesheet load order are subtle
and easy to regress. Add a golden-file test:
- test/render/test-render-{rst,md}.{rst,md}: one rst and one Markdown fixture
(identical content bar extension + title syntax) covering trailing punctuation,
hyphen/em-dash/close-paren after a span, the leading `$-x$` opening-delimiter
case, mid-token non-matches, `\$` escaping, and a multi-line span left untouched.
- test/render/*.intermediate: the golden post-sed output for each.
- test/render-test.sh + `make test`: renders the fixtures via the Makefile
(capturing render.sh's post-sed stream through the new RENDER_INTERMEDIATE hook),
diffs against the goldens, and checks that style.css loads after the KaTeX CSS.
render.sh gains RENDER_INTERMEDIATE, defaulting to /dev/null so normal runs are
byte-for-byte unaffected. The Makefile gains rendered/test/%.html rules (with
css/ and assets/ symlinked so the pages are viewable in a browser) and a `test`
target. The Check Renderability workflow now runs `make test`.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>
ValarDragon
approved these changes
Jun 24, 2026
ValarDragon
left a comment
ValarDragon
left a comment
Collaborator
There was a problem hiding this comment.
Punctuation around math-mode, removal of \small and \text -> \textsf changes LGTM
Didn't re-render anything myself, so utACK
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A batch of fixes to the ZIP rendering pipeline, plus a regression test so they don't silently break again.
Commits
.Makefile.uptodatenow depends on the static files, so editingstyle.cssetc. triggers a re-copy intorendered/(previously a stale copy could be served)..katex .textitcomment now describes what the rule actually does.README.rst(ZIP 258Discussions-To) — fills in ZIP 258'szips#1304discussion link in the generated index (not captured when Add draft NU6.3 deployment and Version 6 Transaction Format ZIPs #1301 landed).render.shrewrites trailing punctuation into the math span robustly: it matches whole$...$spans, so the opening$of a span whose content starts with punctuation (e.g.$-x$) is not corrupted;\textsfin math matches the body font (Roboto); andstyle.cssnow loads after the KaTeX CSS so our.katex .*overrides win the cascade. This let almost all the manual punctuation spacing / line-breaking hacks across ZIPs be removed.100–900weight range and pins emphasis (emand.katex .textit) to weight 500, so pool names render at a consistent weight in running text and in math, on Firefox and Chromium.render.sh's post-sed intermediate output and the stylesheet load order. This is exposed viamake testand wired into the Check Renderability workflow.Filed with the assistance of Claude Opus 4.8 (1M context).