Skip to main content

A Sphinx extension for rendering math in HTML pages

Project description

sphinxcontrib.katex's documentation on Read the Docs sphinxcontrib-katex's supported Python versions sphinxcontrib.katex's MIT 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.

Installation

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

$ 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.

Usage

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

extensions = ['sphinxcontrib.katex']

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

katex_prerender = True

See the Configuration section for all available settings.

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.

katex_css_path = \
    'https://cdn.jsdelivr.net/npm/katex@0.16.22/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.

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.

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:

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:

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}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib_katex-0.9.11.tar.gz (100.5 kB view details)

Uploaded Source

Built Distribution

sphinxcontrib_katex-0.9.11-py3-none-any.whl (98.0 kB view details)

Uploaded Python 3

File details

Details for the file sphinxcontrib_katex-0.9.11.tar.gz.

File metadata

  • Download URL: sphinxcontrib_katex-0.9.11.tar.gz
  • Upload date:
  • Size: 100.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for sphinxcontrib_katex-0.9.11.tar.gz
Algorithm Hash digest
SHA256 2d32b210d20bbee451a51d19645f6fef5f5568b9a54e2813affb96efa661238a
MD5 7883574d79546aeab2f69a85ff397fdf
BLAKE2b-256 9acd71d3c7fc1a4e40a03048ce68787e4e4b6f612dc6b95acc89f5010d4cda7a

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinxcontrib_katex-0.9.11.tar.gz:

Publisher: publish.yml on hagenw/sphinxcontrib-katex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sphinxcontrib_katex-0.9.11-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinxcontrib_katex-0.9.11-py3-none-any.whl
Algorithm Hash digest
SHA256 b0a318d86b8f43314ccdd481ce0db90283ac51f51afd9479969f36a0c291f44e
MD5 939337c404cd1dcd22f0ddc16ce142cb
BLAKE2b-256 3314c62d4553dbf27156b6549ceed1a9768f801c979237a2cf0c3d074e16272f

See more details on using hashes here.

Provenance

The following attestation bundles were made for sphinxcontrib_katex-0.9.11-py3-none-any.whl:

Publisher: publish.yml on hagenw/sphinxcontrib-katex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page