sphinxcontrib-katex

sphinxcontrib-katex

|docs| |python-versions| |license|

A Sphinx extension_ for rendering math in HTML pages.

The extension uses KaTeX_ for rendering of math in HTML pages. It is designed as a replacement for the built-in extension sphinx.ext.mathjax, which uses MathJax for rendering.

• Documentation: https://sphinxcontrib-katex.readthedocs.io/

• Download: https://pypi.org/project/sphinxcontrib-katex/#files

• Development: https://github.com/hagenw/sphinxcontrib-katex/

.. _Sphinx extension: http://www.sphinx-doc.org/en/master/extensions.html .. _MathJax: https://www.mathjax.org .. _KaTeX: https://khan.github.io/KaTeX/ .. _sphinx.ext.mathjax: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/mathjax.py

.. |docs| image:: https://readthedocs.org/projects/sphinxcontrib-katex/badge/ :target: https://sphinxcontrib-katex.readthedocs.io/ :alt: sphinxcontrib.katex's documentation on Read the Docs .. |license| image:: https://img.shields.io/badge/license-MIT-green.svg :target: https://github.com/hagenw/sphinxcontrib-katex/blob/main/LICENSE :alt: sphinxcontrib.katex's MIT license .. |python-versions| image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-katex.svg :target: https://pypi.org/project/sphinxcontrib-katex/ :alt: sphinxcontrib-katex's supported Python versions

Installation

To install sphinxcontrib.katex into your Python virtual environment run:

.. code-block:: bash

$ pip install sphinxcontrib-katex

If you want to pre-render the math by running Javascript on your server instead of running it in the browsers of the users, you have to install nodejs_.

.. _nodejs: https://nodejs.org/

Usage

In conf.py of your Sphinx project, add the extension with:

.. code-block:: python

extensions = ['sphinxcontrib.katex']

To enable server side pre-rendering add in addition (nodejs_ installation needed):

.. code-block:: python

katex_prerender = True

See the Configuration section for all available settings.

.. _nodejs: https://nodejs.org/

Configuration

The behavior of sphinxcontrib.katex can be changed by configuration entries in conf.py of your documentation project. In the following all configuration entries are listed and their default values are shown.

.. code-block:: python

katex_css_path = \
    'https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css'
katex_js_path = 'katex.min.js'
katex_autorender_path = 'auto-render.min.js'
katex_inline = [r'\(', r'\)']
katex_display = [r'\[', r'\]']
katex_prerender = False
katex_options = ''

The specific delimiters written to HTML when math mode is encountered are controlled by the two lists katex_inline and katex_display.

If katex_prerender is set to True the equations will be pre-rendered on the server and loading of the page in the browser will be faster. On your server you must have a katex executable installed and in your PATH as described in the Installation section.

The string variable katex_options allows you to change all available official KaTeX rendering options_, e.g.

.. code-block:: python

katex_options = r'''{
    displayMode: true,
    macros: {
        "\\RR": "\\mathbb{R}"
    }
}'''

You can also add KaTeX auto-rendering options_ to katex_options, but be aware that the delimiters entry should contain the entries of katex_inline and katex_display.

.. _KaTeX rendering options: https://khan.github.io/KaTeX/docs/options.html .. _KaTeX auto-rendering options: https://khan.github.io/KaTeX/docs/autorender.html

LaTeX Macros

Most probably you want to add some of your LaTeX math commands for the rendering. In KaTeX this is supported by LaTeX macros (\def). You can use the katex_options configuration setting to add those:

.. code-block:: python

katex_options = r'''macros: {
        "\\i": "\\mathrm{i}",
        "\\e": "\\mathrm{e}^{#1}",
        "\\vec": "\\mathbf{#1}",
        "\\x": "\\vec{x}",
        "\\d": "\\operatorname{d}\\!{}",
        "\\dirac": "\\operatorname{\\delta}\\left(#1\\right)",
        "\\scalarprod": "\\left\\langle#1,#2\\right\\rangle",
    }'''

The disadvantage of this option is that those macros will be only available in the HTML based Sphinx builders_. If you want to use them in the LaTeX based builders as well you have to add them as the latex_macros setting in your conf.py and specify them using proper LaTeX syntax. Afterwards you can include them via the sphinxcontrib.katex.latex_defs_to_katex_macros function into katex_options and add them to the LaTeX preamble:

.. code-block:: python

import sphinxcontrib.katex as katex

latex_macros = r"""
    \def \i                {\mathrm{i}}
    \def \e              #1{\mathrm{e}^{#1}}
    \def \vec            #1{\mathbf{#1}}
    \def \x                {\vec{x}}
    \def \d                {\operatorname{d}\!}
    \def \dirac          #1{\operatorname{\delta}\left(#1\right)}
    \def \scalarprod   #1#2{\left\langle#1,#2\right\rangle}
"""

# Translate LaTeX macros to KaTeX and add to options for HTML builder
katex_macros = katex.latex_defs_to_katex_macros(latex_macros)
katex_options = 'macros: {' + katex_macros + '}'

# Add LaTeX macros for LATEX builder
latex_elements = {'preamble': latex_macros}

.. _Sphinx builders: http://www.sphinx-doc.org/en/master/builders.html