Metadata-Version: 2.4
Name: sphinxcontrib-katex
Version: 0.9.11
Summary: A Sphinx extension for rendering math in HTML pages
Author: sphinxcontrib-katex Development Team
License: The MIT License
        
        Copyright (c) 2017-2024 sphinxcontrib-katex Development Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
        
Project-URL: repository, https://github.com/hagenw/sphinxcontrib-katex/
Project-URL: documentation, https://sphinxcontrib-katex.readthedocs.io
Keywords: sphinx,latex,katex,math,documentation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: sphinx>=1.6
Dynamic: license-file

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

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