search

DesignSafe-CI / DS-User-Guide

User Guide for DesignSafe
https://www.designsafe-ci.org/user-guide/
0 stars 7 forks source link

Math equations are not correctly displayed #44

Open rinconraul opened 2 weeks ago

rinconraul commented 2 weeks ago

Overview

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

image

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:

image

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.

image

wesleyboar commented 1 week ago

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. ```yml 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 ``` ```yml 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](https://github.com/DesignSafe-CI/DS-User-Guide/compare/feat/gh-44-support-math-poc-do-not-merge). 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).