Skip to content

Render math in Asciidoc and Markdown with KaTeX

Michael Munch requested to merge Munken/gitlab-ce:markdown-mathjax into master

What does this MR do?

Extends gitlab-org/gitlab-ce!4333 to also enable MathJax support for markdown.

This renders mathematics in Markdown or asciidoc using KaTeX library.

The delimiters \[\] and \(\) are chosen for display and inline math respectively since these are commonly used in LaTeX.

This MR also introduces a new setting math_load, which can be either of never, always or auto. In case of never the KaTeX library is never loaded, in case of always it is always loaded and in the case of auto KaTeX will only be loaded if necessary.

The math detection is currently two-fold. During the rendering of markdown or asciidoc, the text is checked for these delimiters. If the text contains these a css and script tag is appended to the page body.

However in order to support rendering of markdown previews, a small javascript script is appended to the application.js. This listenens on document.body for gitlab:math:typeset in which case it will perform the appropriate action.

Are there points in the code the reviewer needs to double check?

LaTeX code uses ^ and \\ heavily. Based on the discussion here I chose to escape these characters. This is done with a Banzai pre-process filter latex_escape_filter.rb.

Why was this MR needed?

Documentation for scientific software needs mathematics.

What are the relevant issue numbers?

gitlab-org/gitlab-ce#13690 and gitlab-org/gitlab-ce#13180

Screenshots (if relevant)

Rendering of static readme.md:
Screenshot_from_2016-10-10_03_41_13

Rendering of dynamic markdown preview:
Screenshot_from_2016-10-10_03_40_52

Merge request reports