imfing
Math fonts are missing after the introduction of SSR math formulas
Description
After the server-side rendering of math formulas functionality is introduced, all KaTeX fonts are removed from this repository. But these fonts are not fetched from elsewhere such as a CDN, making those rendered equations in a very weird look.
Steps To Reproduce
- Checkout the repository to revision b700825943a14d94b5995c7cb759ee625ccff04b
- Write any math equations
- Serve the website and see the rendered formulas
Additionally, the effect can be observed directly on this page served by CD deployment of #589.
Expected Behavior
Fonts should be fetch somehow to make the rendered formulas look normal.
Actual Behavior
Fonts are missing.
Screenshots
A screenshot from https://deploy-preview-589--hugo-hextra.netlify.app/docs/guide/latex/, where the version mentioned above is used:
Environment
- Hugo Version: v0.145.0
- Browser/OS: Edge v134.0.3124.93, Windows
- Theme Version: Since revision b700825943a14d94b5995c7cb759ee625ccff04b
Additional Context
If I understand correctly, the following code snippet fetches a KaTeX CSS file from the CDN, and then save it to the generated website's directory, without patching its content
https://github.com/imfing/hextra/blob/83fda0109f55a16476bd404cf00b75784095d1da/layouts/partials/head.html#L66-L74
In katex.min.cxx, the URL of those fonts are relative to not a CDN but the docs website, leading to 404 errors.
Hi @oosquare thanks for the report!
to clarify, the server-side rendering introduced in #589 uses MathML output, which should render correctly without requiring KaTeX fonts or CSS.
According to MDN, "Since January 2023, this feature works across the latest devices and browser versions.", so I guess somehow in your browser it falls back to html output which leverages the KaTeX CSS styles, and hence requiring KaTeX fonts.
Can you confirm your Edge browser version? Meanwhile, let's look into a fallback option to include fonts only when needed.
@imfing thanks for your reply.
Can you confirm your Edge browser version? Meanwhile, let's look into a fallback option to include fonts only when needed.
The version of Edge is 134.0.3124.93.
Indeed, MathML should be supported well by all mainstream browsers so far. But I now suspect the root of cause is not the browser itself, instead, this is because MathML requires additional fonts to work properly. I also tested #589 deployment on FireFox, and the result turned to be same as that on Edge. I refered to examples about MathML on MDN, and then I found that some formulas were also rendered abnormally, while those code snippets with additional fonts included worked as expected. The key difference is <link rel="stylesheet" href="https://fred-wang.github.io/MathFonts/LatinModern/mathfonts.css" />.
You can examine the difference between formulas from the following two pages:
- Without
mathfonts.css: https://developer.mozilla.org/en-US/docs/Web/MathML/Tutorials/For_beginners/Getting_started - With
mathfonts.css: https://developer.mozilla.org/en-US/docs/Web/MathML/Tutorials/For_beginners/Scripts
I'll try to update my PR to adopt this alternative solution. Any suggestion is highly appreciated.
I'd like to add some mroe information here. According to hugo transform.ToMath documentation, this function by default renders LaTeX formulas to MathML. On the other hand, if formulas are processed with option output set to either html or htmlAndMathml, the rendered output will be in a KaTeX style, thus relevant CSS files are required.
Even though htmlAndMathml also makes MathML output available, KaTeX output takes precedence over MathML output and suppresses the latter one. So the weird output in #589 CD is actually different from examples from MDN in the underlying mechanism. In #589 CD, that's because KaTeX output requires KaTeX CSS, while in examples from MDN, the reason is that MathML simply can't have a good look due to the absence of fonts such as Latin Modern.
So for the solution of this problem, there are two viable solutions. One is to stick to KaTeX at the cost of more overhead, but with benefits such as better backward compatibility and more consistent rendering comparing with other website. Another one is to use the more lightweight MathML, where only a small amount of fonts are required, which can be fetched from CDN or published along with the site deployment.
@oosquare Thanks for the detailed explanation. I was already aware that PR #589 used the htmlAndMathml option, which is recommended by Hugo.
What confused me was that I couldn’t reproduce the same rendering behavior on my end. I tested on macOS (Chrome & Firefox) and Windows (Edge 134.0) - the fonts were not correctly fetched, but the math equations are properly rendered with system fonts.
the reason is that MathML simply can't have a good look due to the absence of fonts such as Latin Modern.
That makes sense. System fonts might be the culprit for the displaying issue here, given that your system (in CJK language) may not have the math fonts needed, thus the browser falls back to other default latin font which was not intended for math.
So for the solution of this problem, there are two viable solutions. One is to stick to KaTeX at the cost of more overhead, but with benefits such as better backward compatibility and more consistent rendering comparing with other website. Another one is to use the more lightweight MathML, where only a small amount of fonts are required, which can be fetched from CDN or published along with the site deployment.
In earlier versions like 0.9.7, all necessary fonts were bundled with the theme, which helped with this. But now with server-side rendering introduced, I think the benefits outweigh the drawbacks, and we could bring back the fonts via CDN (like your PR #656) or package them with the site deployment.