A `Sphinx extension`_ for rendering math in HTML pages.
Project description
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-hypernode.com/project/sphinxcontrib-katex/#files
Development: https://github.com/hagenw/sphinxcontrib-katex/
Usage
Installation:
pip install sphinxcontrib-katex
In conf.py of your sphinx project, add the extension with:
extensions = ['sphinxcontrib.katex']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.10/dist/katex.min.css'
katex_js_path = \
'https://cdn.jsdelivr.net/npm/katex@0.10/dist/katex.min.js'
katex_autorender_path = \
'https://cdn.jsdelivr.net/npm/katex@0.10/contrib/auto-render.min.js'
katex_inline = [r'\(', r'\)']
katex_display = [r'\[', r'\]']
katex_options = ''The specific delimiters written to HTML when math mode is encountered are controlled by the two lists katex_inline and katex_display.
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}Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinxcontrib-katex-0.4.1.tar.gz.
File metadata
- Download URL: sphinxcontrib-katex-0.4.1.tar.gz
- Upload date:
- Size: 10.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.5.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | cba7ac07c64d63dab5f2fea86602e0c49acf1ed0c34e8004f9e249a98ccc3a48 |
|
| MD5 | 6b1f3c4784b27cf501a504f5e5fa034b |
|
| BLAKE2b-256 | ccb8500910733c116a05f0c7a6e383d9d1f43456027f46e19eab04da8dafa471 |
File details
Details for the file sphinxcontrib_katex-0.4.1-py2.py3-none-any.whl.
File metadata
- Download URL: sphinxcontrib_katex-0.4.1-py2.py3-none-any.whl
- Upload date:
- Size: 8.1 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.5.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ab5af14666be7e39973302770b740b63d39d945c6e08acb2b7b1a24b3a6b2dbd |
|
| MD5 | d05fdd4b74d68a169802c49c07381318 |
|
| BLAKE2b-256 | ec730521186c5044713abbaff4bf221cb62dab8826f6f6c6279a38638df374ca |
