Skip to main content

katex extension for Python Markdown

Project description

markdown-katex

This is an extension for Python Markdown which adds KaTeX support.

```math
f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi
```

Project/Repo:

MIT License Supported Python Versions PyCalVer v202006.1021 PyPI Version PyPI Downloads

Code Quality/CI:

Build Status Type Checked with mypy Code Coverage Code Style: sjfmt

Name role since until
Manuel Barkhau (mbarkhau@gmail.com) author/maintainer 2019-05 -

Install

$ pip install markdown-katex

This package includes the following binaries:

  • katex-v0.11.1-x86_64-Linux
  • katex-v0.11.1-x86_64-Macos
  • katex-v0.11.1-x86_64-Windows

If you are on a different platform, or want to use a more recent version of katex-cli, you will need to install it via npm.

$ npx katex
$ npx katex --version
0.11.1

This extension will always use the locally installed version of KaTeX if it is available, instead of using the implementation bundled with this package.

No JavaScript is required to render the resulting HTML, so it can be used with more limited renderers (which don't support JavaScript) such as WeasyPrint .

Usage

Formulas can be created and edited interactively using the editor on katex.org. They also have some good documentation for the subset of LaTeX that is supported. When embedding these in your Markdown files, they must be marked with a special syntax in order to be rendered using KaTeX. There are many syntax extensions for Markdown that allow LaTeX formulas to be embedded, however this package only supports the syntax introduced by Gitlab:

  • For inline mode formulas: $`...`$
  • For display mode formulas: ```math

Here is an example that uses this syntax.

There are two main advantages of this syntax:

  1. Gitlab has an existing Markdown renderer that can be used without the need to download any software. This implementation also uses KaTeX, so the output should be exactly the same as this extension.
  2. The fallback behaviour of other Markdown renderers is to render the raw LaTeX as inline code or a code block. This means that they won't inadvertently parse a LaTeX formula as Markdown syntax.

Hopefully other renderers will also adopt support for this syntax as:

  1. Rendering is done in the browser using KaTeX so implementation effort and should be minimal.
  2. The false positive rate for existing Markdown documents is negligible (ie. existing alternate use of $` syntax is minimal to non-existent).

Options

  • no_inline_svg: Replace inline <svg> with <img data:image/svg+xml;base64.."> tags.
  • insert_fonts_css: Insert font loading stylesheet (default: True).

Development/Testing

$ git clone https://gitlab.com/mbarkhau/markdown-katex
$ cd markdown-katex
$ make install
$ make lint mypy test

MkDocs Integration

In your mkdocs.yml add this to markdown_extensions.

# mkdocs.yml
markdown_extensions:
  - markdown_katex:
      no_inline_svg: True
      insert_fonts_css: True
      macro-file: macros.tex

The macro-file might looks something like this:

% macros.tex
\mymacro:\text{prefix #1 suffix}

Changelog for https://gitlab.com/mbarkhau/markdown-katex

v202006.1021

  • Fix #7: File encoding issue on Windows.

v202006.1020

  • Fix #7 katex-cli on Windows (now uses pkg --target node12...)
  • Fix search for local katex.ps1, katex.cmd, katex.exe on Windows.

v202005.0017

v202005.0016-beta

v202004.0015-beta

v202004.0014-beta

v202001.0013-beta

  • Fix: Ignore trailing whitespace after closing fence.

v202001.0012-beta

  • Fix: Remove extraneous whitespace to work better with whitespace: pre.

v201912.0011-beta

  • Add option insert_fonts_css
  • Document options

v201910.0010-beta

  • Add more prominent example to README.md
  • Fix #2: Fix spurious log message when using MkDocs

v201908.0009-beta

  • Fix #1: Wrong formulas are rendered when multiple formulas are in one doc.

v201907.0008-beta

  • Fix: don't require typing package for py<35

v201905.0007-beta

  • Fix: Parsing of inline code when using multiple backticks

v201905.0004-beta

  • Fix: better error reporting
  • Fix: cleanup temp dir

v201905.0002-alpha

  • Initial release

Download files

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

Files for markdown-katex, version 202006.1021
Filename, size File type Python version Upload date Hashes
Filename, size markdown_katex-202006.1021-py2.py3-none-any.whl (48.0 MB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size markdown-katex-202006.1021.tar.gz (47.7 MB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page