Math equations are not correctly displayed

[rinconraul]

Overview

Math equations in the use cases (and any other page) will not be correctly rendered.

MathJax - Possible solution (test 1)

Adding to mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

It works, but at the same time, it also renders HTML-style code:

KaTeX - It seems this is not a solution (test 2)

Adding to mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/katex.js
  - https://unpkg.com/katex@0/dist/katex.min.js
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
  - https://unpkg.com/katex@0/dist/katex.min.css

It does not render the equations, it displays HTML code, and it seems it brings back to the previous theme.

[wesleyboar]

Yes, the mkdocs.yml must be updated to support this.

I used MathJax successfully (no { ... } rendering errors), but (since #46 a.k.a. redesign) one must be careful not to lose TACC's extra_css and extra_javascript.

changes to configuration

The - ... represents all entries from the URL in the comment after it.

extra_javascript:
  # TACC/TACC-Docs:/mkdocs.base.yml
  - ... # https://github.com/TACC/TACC-Docs/blob/main/mkdocs.base.yml#L38-L40
  # DesignSafe/DS-User-Guide
  # https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-mathjax
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js

markdown_extensions:
  # TACC/TACC-Docs:/mkdocs.base.yml
  - ... # https://github.com/TACC/TACC-Docs/blob/main/mkdocs.base.yml#L45-L65
  # DesignSafe/DS-User-Guide
  # https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-mathjax
  - pymdownx.arithmatex:
      generic: true

You may see and test the complete changeset. This is a proof-of-concept. Do not create a PR with this change.

To make this less of a mess to configure, I will make changes upstream (TACC/TACC-Docs).

[rinconraul]

Going back to this issue, I added the configuration code to the use case in which I wanted the equations to render

<script type="text/x-mathjax-config">
MathJax.Hub.Config({  
jax: ["input/TeX", "output/HTML-CSS"],
extensions: ["tex2jax.js"],
"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"] },
tex2jax: { inlineMath: [ ["$", "$"], ["\\(","\\)"] ], displayMath: [ ["$$","$$"], ["\\[", "\\]"] ], processEscapes: true, ignoreClass: "tex2jax_ignore|dno" }, 
TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } } },
messageStyle: "none"  
});

and it works perfectly in the new TACC's documentation implementation (see PR #106).
Should we do this instead of directly editing the mkdocs.yml?