Sphinx not rendering LaTeX equations in `.ipynb` and `.md` files

[PanJi-0]

Hello,

I'm using the Python package template from the book and encountered an issue with LaTeX math equations in .ipynb and .md files not rendering correctly in the generated HTML using Sphinx. Specifically, the inline math like $x + y = z$ and block math like $$x + y = z$$ are not displayed as expected in the final documentation.

Steps I’ve taken:

1. I added the following configuration to conf.py:

   extensions = [
       "myst_nb",
       "autoapi.extension",
       "sphinx.ext.napoleon",
       "sphinx.ext.viewcode",
       "sphinx.ext.mathjax",  # Added MathJax extension
   ]
   
   myst_enable_extensions = [
       "amsmath",  # To support LaTeX math in markdown
   ]
   
   mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS-MML_HTMLorMML"

2. I cleaned and rebuilt the documentation using:

   make clean
   make html

The problem:

Even after following the above steps which I learnt from ChatGPT and Google, LaTeX equations in both .ipynb and .md files are not rendering in the final HTML output. The equations appear as plain text rather than formatted math.

Environment:

macOS Sonoma 14.5 All other settings and configurations are equivalent to those of pycount in the book.

Thank you!

[TomasBeuzen]

Hello @PanJi-0 - thanks for raising your issue. What version of Python are you using?

I need to update the version used in the book (currently 3.9). But I tried with Python 3.10 and could render equations on my MacOS Sonoma 14.5, here's what I did:

1. Created an environment with Python 3.10
2. Installed all necessary dependencies to render documentation as outlined in the book
3. Added the mathjax extension to the config file

   extensions = [
   "myst_nb",
   "autoapi.extension",
   "sphinx.ext.napoleon",
   "sphinx.ext.viewcode",
   "sphinx.ext.mathjax",
   ]

4. Included the mathjax source link

   mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS-MML_HTMLorMML"

5. There are two ways I could render equations in .md or .ipynb files, using dollar signs, or the {math} directive as follows:

   
   * Dollar sign notation

$$x + y = z$$

$$(a - b)^2 = a^2 - 2ab + b^2$$

• Math directive notation

x + y = z

(a - b)^2 = a^2 - 2ab + b^2

I've included all files in a ZIP here for your reference.

![image](https://github.com/user-attachments/assets/2a687e1b-8a1d-4915-a145-d6f5239d0adc)

[docs.zip](https://github.com/user-attachments/files/17319809/docs.zip)

[PanJi-0]

Thank you so much for your help! The Python version I used is 3.9. I didn’t realize that this could be a contributing factor. I’ll give it a try with Python 3.10 as you suggested.

[PanJi-0]

Thank you! It works. The block equations now render perfectly using both methods.

For inline equations, I find that if the file contains:

```{math}
...
```

then using \\(...\\) works for rendering inline equations. But without this structure, I have no idea how to make inline math render correctly.

Anyway, the solution works well enough for my current needs.

Thanks again for your support!