markdown-it-texmath

Add TeX math equations to your Markdown documents rendered by markdown-it parser. KaTeX is used as a fast math renderer.

What's New?

* markdown-it-texmath reached quite a stable state with version 1.0 .
* Native begin{...} / end{...} environments are supported as delimiters itself ... thanks to William Stein for proposing.

``
\begin{equation}
a^2+b^2=c^2
\end{equation}
`
They can even be nested.
`
\begin{equation}
\begin{pmatrix}
A & B \\ B & C
\end{pmatrix}
\end{equation}
`

* Different delimiters can be merged. Delimiters options property supports array notation for that. Example: delimiters: ['dollars','beg_end']. Thanks to Liu YongLiang for proposing.

Features

Simplify the process of authoring markdown documents containing math formulas.
This extension is a comfortable tool for scientists, engineers and students with markdown as their first choice document format.

* Macro support
* Simple formula numbering
* Inline math with tables, lists and blockquote.
* User setting delimiters:
* 'dollars' (default)
* inline: $...$ or $$...$$
* display: $$...$$
* display + equation number: $$...$$ (1)
* 'brackets'
* inline: \(...\)
* display: \[...\]
* display + equation number: \[...\] (1)
* 'doxygen'
* inline: \f$...$\f
* display: \f[...\f]
* display + equation number: \f[...\f] (1)
* 'gitlab'
* inline: $...$
* display: `math ... `
* display + equation number: `math ... ` (1)
* 'julia'
* inline: $...$ or ` ... `
* display: `math ... `
* display + equation number: `math ... ` (1)
* 'kramdown'
* inline: $$...$$
* display: $$...$$
* display + equation number: $$...$$ (1)
* 'beg_end' (display math only)
* inline: N/A
* display: begin{...}...end{...}
* display + equation number: N/A

Show me

View a test table.

try it out ...

Use with node.js



Install the extension. Verify having markdown-it and katex already installed .
`
npm install markdown-it-texmath
`
Use it with JavaScript.
`js
const tm = require('markdown-it-texmath');
const md = require('markdown-it')({html:true})
.use(tm, { engine: require('katex'),
delimiters: 'dollars',
katexOptions: { macros: {"\\RR": "\\mathbb{R}"} } });
const str = "Euler\'s identity $e^{i\\pi}+1=0$ is a beautiful formula in $\\RR^2$.";

md.render(str);
`

Use in Browser

`html

`

CDN

Use following links for texmath.js and texmath.css
* https://cdn.jsdelivr.net/npm/markdown-it-texmath/texmath.min.js
* https://cdn.jsdelivr.net/npm/markdown-it-texmath/css/texmath.min.css

Dependencies

* markdown-it: Markdown parser done right. Fast and easy to extend.
* katex: This is where credits for fast rendering TeX math in HTML go to.

ToDo

nothing yet

FAQ

* __Support of inline syntax of display math ?__
Inline syntax of display math with dollars mode is supported starting from version "0.7.0". So 'This formula $$a+b=c$$ will result in display math presentation', i.e. gets displayed on a separate line. For true* inline math use $..$ mode like before.

* __Multiline diplay math in blockquote block possible ?__
* Display math inside of blockquote blocks is able to span multiple lines with version "0.7.3".

* __markdown-it-texmath with React Native does not work, why ?__
* markdown-it-texmath is using regular expressions with y (sticky) property and cannot avoid this. The use of the y flag in regular expressions means the plugin is not compatible with React Native (which as of now doesn't support it and throws an error Invalid flags supplied to RegExp constructor).

* __Why doesn't markdown-it-texmath work with other engines ?__
* markdown-it-texmath is a personal project of mine. As it does very well with KaTeX what I want it to do, I offer it to the public as an open source plugin. I do not have time or interest to integrate other math engines.
But if someone wants to help here out, pull requests are always welcome.

CHANGELOG

$3

* Update to KaTeX version 0.15.6.
* Update to markdown-it 13.0.1.
* Bug fixed in level handling with markdown-it. Thanks to williamstein.
* Bug fixed in mapping with markdown-it. Thanks to williamstein.
* Supporting native begin{..} / end{...} environments as delimiters itself. Thanks to williamstein for proposing.
* Merging different delimiters for simultaneous use via delimiters:[, ]. Thanks to tlylt for proposing.

$3

* Redundant end-tag with display-mode equations removed. All modes were affected ... invisible effect though. Thanks to yuanbug for reporting.

$3

* Small bug in 'dollars' inline-display-mode regex fixed.

$3

* More Optimization done with the 'dollars' regexes.

$3

* Optimizing the 'dollars' regexes. Thanks to Erik Demaine.
* Adding 'doxygen' delimiters support. (#31). Thanks to arwedus.

$3

* Fixing newline bug in 'dollars' regexes. (#32).

$3

* Fixing disability to include escaped dollar when using dollars delimiters (#32).

$3

* potential XSS vulnerability with equation numbers fixed (#29).

$3

* KaTeX options {katexOptions:...} within markdown-it-texmath options are directly handed over to katex. See KaTeX options. Thanks to Kirill for pull request.
* Potential error message XSS vulnerability fixed. Thanks to CatNose.
* Using new boolean markdown-it-texmath outerSpace option, inline rules dollars explicitly require surrounding spaces when set to true (default is false for backwards compatibility). This is primarily a guard against misinterpreting single $'s in normal markdown text.
* Update to KaTeX version 0.13.11.

$3

* Infinite loop bug with gitlab mode and display math inside blockquote section removed.
* Fundamental redesign of display math implementation.
* Update to KaTeX version 0.12.0.

$3

* Regex bug with gitlab mode removed.

$3

* Experimental pandoc mode removed. Enhanced dollars mode now does, what pandoc mode was requiring.
* With dollars mode inline math expression $$..$$ will result in display math presentation now. Adding equation numbers $$..$$(1) is not supported in inline syntax.
* Significant code redesign and regular expression optimization results in more compact code and performance gain ... not measured though.
* Bug with display math inside of blockquote blocks removed.

$3

* Now display math inside of blockquote blocks can span multiple lines, provided that every line starts with a > character.
* Possible cause of [blockquote bug(https://github.com/goessner/mdmath/issues/50)] presumably eliminated.
* Update to markdown-it version 11.0.0

$3

* Now supporting katex options. Thanks goto Kirill.

$3

* Removed a small bug in activation method.

$3

* Hand instance of katex over to markdown-it-texmath using options.engine object. Works with node.js and browsers. With node.js options.engine entry { engine:'katex' } as a string also works.
* As a consequence of the topic before, the use method of markdown-it-texmath is deprecated now.
* Add beta support for Pandoc syntax on request. Here waiting for test results.
* Using jsdelivr as cdn from now on.

$3

* Add support for Julia Markdown on request.

$3

* Remove rendering bug with brackets delimiters.

$3

* Remove pathological bug within blockquotes.

$3

* Add support for Tex macros (https://katex.org/docs/supported.html#macros) .
* Bug with brackets delimiters .

$3

* Add support for Kramdown .

$3

* Fatal blockquote bug investigated. Implemented workaround to vscode bug, which has finally gone with vscode 1.26.0 .

$3

* Escaped underscore bug removed.

$3

* Backslash bug removed.

$3

* Modifying the block mode regular expression with gitlab delimiters, so removing the newline bug.

License

markdown-it-texmath` is licensed under the MIT License

© Stefan Gössner