fast, pure-Ruby Markdown-superset converter

Math Engine MathJax

MathJax is a javascript library that uses the TeX algorithms and fonts to display math formulas on HTML pages. It allows for very fine-grained configuration, is widely used and works on all modern browsers.

This engine marks up math formulas with HTML <script type="math/tex"> tags that MathJax understands. The only other thing to do is to include the MathJax library itself on the HTML page.

Note that kramdown does not ship with the MathJax library and that therefore the “default” template does not include a link to it! The MathJax documentation describes how to add a link to MathJax to your page.

Using KaTeX instead of MathJax

To use KaTeX instead of MathJax, activate the MathJax engine in kramdown, include the KaTeX Javascript files in the HTML file and put the following script at the end of the HTML file (note that JQuery is used for some parts but it can probably be done without it):

  $("script[type='math/tex']").replaceWith(function() {
      var tex = $(this).text();
      return katex.renderToString(tex, {displayMode: false});

  $("script[type='math/tex; mode=display']").replaceWith(function() {
      var tex = $(this).html();
      return katex.renderToString(tex.replace(/%.*/g, ''), {displayMode: true});

Note that including the KaTeX Javascript files and the above script is normally done using a template file (see the template option.

See this comment for more details.


The MathJax engine supports the following keys of the option ‘math_engine_opts’:

Specifies whether a preview should be shown. It defaults to false but if set to true, a preview with the LaTeX code itself is shown. If it is set to any value other than false or true, that value is shown as the preview.
When true, wraps the LaTeX code in code / pre > code tags instead of span / div tags, mirroring the structure of inline code / code blocks. This ensures the content is styled like regular code and improves legibility in RSS readers, text browsers, etc.

To prevent styling issues after MathJax has loaded, consider adding .MathJax_Preview:empty { display:none } to your CSS.

Defaults to false and only works if preview is true.