In-line math alignment

[adrybakov]

Hello,

I encountered a problem with math's rendering on pages produced by sphinx-gallery. It does not occur on their documentation web-page, but does occur when I build documentation of my project.

Here is misaligned version:

Here is version that is build with proposed change:

I do not have experience with css styling, perhaps proposed solution is not an adequate one.

I would be grateful if someone with more experience can comment on this topic.

Best,
Andrey

[drammock]

I think we need more information than the 2 small screenshots you've provided. Here's an example with in-line math on a sphinx-gallery-generated page that doesn't have that problem:

https://mne.tools/dev/auto_examples/preprocessing/eeg_bridging.html#compare-bridging-across-subjects-in-the-eegbci-dataset

The first paragraph of that section has several inline :math: roles, they all look OK to me. Here's another example from the same docs, but in a function docstring (so, a page not built by sphinx-gallery):

https://mne.tools/dev/generated/mne.preprocessing.find_bad_channels_maxwell.html#mne.preprocessing.find_bad_channels_maxwell

In the "notes" section of that docstring there are several, most notably in item 5 of the numbered list. Again they all look fine (and not noticeably different from on the sphinx-gallery-generated page).

So, can you say more about exactly what conditions cause the error? Simply using sphinx-gallery doesn't seem to be enough to trigger the problem. Links to the docs / pages in question would help. Even better would be a minimal example site (e.g., starting from sphinx-quickstart) that has 1 "normal" page and 1 sphinx-gallery-generated page, both with in-line :math: roles. It would also be helpful to test that minimal site with at least 1 other sphinx theme to see if it still happens there (but not jupyter-book theme, it inherits from this one).

[adrybakov]

Thanks for the reply, the examples from your links look normal for me as well.

The bug happens on this web-site:

https://docs.wulfric.org/en/latest/

when option align-items: baseline; is turned off (I turn it off with inspect tool of Google Chrome) or if the project is build without

/* Fix math alignment in sphinx-gallery*/
span.math {
    display: inline-flex;
    align-items: baseline;
}

in docs/source/_static/wulfric.css

Note, that by default this option is turned on, thus no bug is visible.

Bug occurs on the page

https://docs.wulfric.org/en/latest/user-guide/conventions/bravais-lattices/2_sc/plot_01_CUB.html

just on top of it: symbol a in "Cubic cell is defined by single parameter a." That page is produced by sphinx-gallery.

No bug occurs on another one, that is not produced by sphinx-gallery

https://docs.wulfric.org/en/latest/user-guide/conventions/basic-notation.html

I will try to prepare minimal project that reproduces this bug in the following days.

[drammock]

OK so at a glance: Your sphinx-gallery-generated page has a different internal structure for the mathjax elements. SG-pages have (simplified):

<span class="math notranslate nohighlight">
    <span class="MathJax_Preview" ...></span>
	<span class="MathJax_SVG" ...>
		<svg>...</svg>
		<span class="MJX_Assistive_MathML" ...>
			<math ...>...</math>
		</span>
	</span>
	<script ...>...</script>
</span>

whereas the non-SG pages have:

<span class="math notranslate nohighlight">
	<mjx-container class="MathJax CtxtMenu_Attached_0" ...>
		<mjx-math class="MJX-TEX" ...>
			<mjx-mi class="mjx-b mjx-i">
				<mjx-c class="mjx-c1D493 TEX-BI"></mjx-c>
			</mjx-mi>
		</mjx-math>
		<mjx-assistive-mml ...>
			<math ...>
				<mi ...>...</mi>
			</math>
		</mjx-assistive-mml>
	</mjx-container>
</span>

So the nodes are different (e.g. span vs mjx-container at the top level) and the classes are different. I don't know why (different versions of MathJax used during SG build vs the rest of the site? seems weird but probably possible). If I look at the page source for the two links I provided from MNE-Python docs, both have mjx-container as the outermost mathjax node.

[adrybakov]

So I prepared the small demo: pst-2255.tar.gz

My local environment

MacOS 13.7.7
Python 3.13.5 [Clang 15.0.0 (clang-1500.1.0.2.5)]
Version of PYPI packages can be found in "environment.txt"

Steps to build:

1. Prepare virtual environment python3.13 -m venv .venv
2. Activate it source .venv/bin/activate
3. Install requirements pip install -r requirements.txt --no-cache
4. Build the docs make html

How the bug looks like

What I found out

1. There is no bug at all with three other themes (furo, alabaster and readthedocs theme)

   

2. Bug disappears if I remove

   import plotly.io as pio
   
   pio.renderers.default = "sphinx_gallery"
   

   from the "docs/source/conf.py". However, it is not an option in the real project (wulfric.org), as if those lines are removed, then no plotly plots are rendered.

   In the configuration file of the sphinx-gallery web-page those lines are not present, however, they advise to include them for plotly gallery. In my case those lines are necessary.

3. Bug only appears if some plotly graph is plotted. It does not appear with matplotlib or plain gallery with no plots.

   

4. Bug is always present in Google Chrome, but in Safari it is more tricky: when I enter the page there is no bug, but if I reload the page - bug appears

   Screen.Recording.2025-08-30.at.00.52.34.mov

Summary

The bug needs at least three components to appear pydata theme + sphinx gallery. + plotly figure (with those lines in conf.py). It might not be the bug specifically of the pydata theme. However, as at least three other themes handle the same demo gallery without any problems, the fix on the side of pydata theme seems to be appropriate.