Use MathJax instead of KaTeX
Release notes
LaTeX equations on markdown are properly rendered using MathJax
Problem to solve
GitLab currently uses KaTeX for rendering equations, which is lightweight but limited in features, leading to user frustration:
Proposal
Replace KaTeX with MathJax
-
Add MathJax as dependency -
Configure to use $ for inline comments (this is disabled by default) -
Remove KaTeX related code
Intended users
Data Scientists, Machine Learning Engineers
User experience goal
The equations rendered on GitLab should match those if the notebook is opened at nbviewer.jupyter.org
For example:
Expected Output: https://nbviewer.jupyter.org/urls/gitlab.com/quantumturbulence/rotating_quantum_turbulence_ufg/-/raw/branch/default/Figures/VortexLength.ipynb#Analysis
Example:
KaTeX | MathJax |
---|---|
Further details
We could instead upgrade KaTeX to the latest version, which has more features but it still limited. The example above won't work for example since KaTeX doesn't support defining the command and then using it later
Usability of MathJax is a lot simpler, it works by simply adding the dependency, while KaTeX require some additional configurations.
Documentation
https://docs.gitlab.com/ee/user/markdown.html#math
Availability & Testing
This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier.
What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing?
Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance.
- Unit test changes
- Integration test changes
- End-to-end test change
See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning