Issue with equation rendering inside code annotations

[sdelquin]

Context

Equations inside markdown pages.

Bug description

I have a .md with some equations. All of them are properly rendered, but those inside code annotations are not.

For example:

$a = b^2$

```pycon
>>> x = 3 ** 2#(1)!
```
{ .annotate }

1. $x = 3^2$

Is rendered like so:

Related links

• https://zensical.org/docs/authoring/math/
• https://zensical.org/docs/authoring/code-blocks#code-annotations

Reproduction

reproduction.zip

Steps to reproduce

1. Unzip
2. uv sync
3. uv run zensical serve
4. Look at "Get started" page

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[squidfunk]

Thanks for reporting. Moving to UI repository.

[squidfunk]

It works sometimes, and other times it doesn't:

Your reproduction was crafted from a bootstrapped project, which is the way to do it. However, tote that the bootstrapped project uses a slightly different workflow – it doesn't not subscribe to document, but renders MathJax inline. This is our fault, since we use this integration in the demo template CC @alexvoss – we need to change this.

If I use the workflow that we mention in the documentation, the formula renders consistently:

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

// This is the important part
document$.subscribe(() => { 
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

If this still does not work in your case, please provide another focused reproduction that showcases the problem. I wasn't able to trigger it when using the recommended configuration. Tested in Chrome and Firefox.

[alexvoss]

In addition to adding the JavaScript lines you may also want to remove the async attribute in the first script tag in the Maths section. For me that is the part that produces a stable rendering.

Note that the example page loads MathJax manually, which is not what you should to in your project. There is a note about this on the page that advises you properly configure Maths in your project. We wanted to showcase Maths without forcing every single project starting with zensical new to include it.

[alexvoss]

The issue should be resolved in the bootstrap project delivered with Zensical as of Zensical 0.0.28, which was just released.

[sdelquin]

Issue is still opened for me.

I'm using Zensical 0.0.28. Here you have a reproduction:
reproduction-v2.zip

1. Unzip file.
2. uv sync
3. uv run zensical serve
4. Open http://localhost:8000/
5. Navigate with the right side menu until the section called "Clausuras". Click on it.

6. Open this code annotation:

[alexvoss]

Ok, so it looks like the order in which the local JS and the MathJax library are specified in the zensical.toml is the factor here. With Zensical, the scripts are included in the order in which they are specified, whereas MkDocs includes them in the reverse order.

I am not sure if we should fix the bootstrap template here or change Zensical to match what MkDocs does. The latter would seem odd to me since the behavior of MkDocs is (a) undefined as far as I know and (b) counterintuitive. @squidfunk?

[squidfunk]

Thanks for reporting. This is an entirely different case than the previously provided minimal reproduction – the page is huge, and yes, I can observe some problems with it. It uses tons of code annotations, and sounds like there might be a synchronization issues. This problem is not exclusive to Zensical – it also already happens with Material for MkDocs.

I'll look into this once I got some more time on my hands.