Toshiki's Note

Appearance

@andatoshiki/markdown-it-katex ​

Author:Anda Toshiki
Updated:3 months ago
Words:1.1k
Reading:7 min

Add graceful KaTeX\KaTeX rendering to your Markdown like a charm with markdown-it plugin.

1: Installation ​

Before you start using this plugin, make sure you have already installed the default markdown-it parser; if not, please run the following command or refer to the official markdown-it documentation.

sh
$ npm install markdown-it --save
$ npm install markdown-it --save

First install package with your preferred package manager (npm, yarn, pnpm), or include javascript before the closing </body> for markdown-it-katex's core utils to be loaded for the static page.

sh
$ npm install -D @andatoshiki/markdown-it-katex
$ npm install -D @andatoshiki/markdown-it-katex
sh
$ yarn add --dev @andatoshiki/markdown-it-katex
$ yarn add --dev @andatoshiki/markdown-it-katex
sh
$ pnpm add -D @andatoshiki/markdown-it-katex
$ pnpm add -D @andatoshiki/markdown-it-katex
html
<!-- your other body contents ... -->
    <script src="https://unpkg.com/@andatoshiki/markdown-it-katex@0.0.3/markdown-it-katex.min.js"></script>
</body>
<!-- your other body contents ... -->
    <script src="https://unpkg.com/@andatoshiki/markdown-it-katex@0.0.3/markdown-it-katex.min.js"></script>
</body>

Including KaTeX CSS is necessary in the way you are convenient with, either link the stylesheet from a third party CDN into the local HTML <head> tag or import it into a currently linked CSS stylesheets to enable styles for KaTeX globally as follows,

Or, you could clone or download the entire repository source of KaTeX and self load the fonts/styles/scripts locally, but if you prefer loading from third-party CDN with faster load speed when deployed to save your server resources, the following CDN links might be your choice, you can always switch to other platforms based on your need.

html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
html
<link rel="stylesheet" href="https://gcore.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
<link rel="stylesheet" href="https://gcore.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
html
<link rel="stylesheet" href="https://fastly.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
<link rel="stylesheet" href="https://fastly.jsdelivr.net/npm/katex@0.16/dist/katex.min.css" />
html
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.0/katex.min.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.0/katex.min.css" />
html
<link rel="stylesheet" href="https://unpkg.com/katex@0.16.0/dist/katex.min.css" />
<link rel="stylesheet" href="https://unpkg.com/katex@0.16.0/dist/katex.min.css" />
scss
// ... your other styles
@import 'https://cdnjs.toshiki.dev/ajax/libs/KaTeX/0.16.0/katex.min.css';
// ... your other styles
@import 'https://cdnjs.toshiki.dev/ajax/libs/KaTeX/0.16.0/katex.min.css';

If you are using the default markdown-it parser, I personally recommend that you use the GitHub markdown CSS (github-markdown-css) for styling your HTML output with a similar style replica of GitHub's markdown styling to your familiarity.

html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/github-markdown-css@5.2.0/github-markdown.min.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/github-markdown-css@5.2.0/github-markdown.min.css" />

This forked project maintained by Anda Toshiki comes with the update of KaTeX components with higher style version support (this documentation uses KaTeX version 16.0, without hassels), later versions may works, but no guarantees are given by the developers, if you are not obsessed with the latest released version, 16.0 may fits your need for loading KaTeX on a personal blog site or small educational sites; yet it should work fully functionally.

Warning

Since this project is a fork of the original markdown-it-katex project that hasn't been receiving any active updates of its code source for years, the latest katex style version supported is somewhere around ver. 0.9.0 which clearly is outdated and results in broken styles with overflowing and other potential bug presents.

2: Usage ​

RTo render equations, you need to include the markdown-it-katex plugin in the markdown-it components in your JavaScript or TypeScript file as follows,

js
var md = require('markdown-it')(),
    mk = require('andatoshiki/markdown-it-katex')

md.use(mk)

// double backslash is required for javascript strings, but not html input
var result = md.render('# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$')
var md = require('markdown-it')(),
    mk = require('andatoshiki/markdown-it-katex')

md.use(mk)

// double backslash is required for javascript strings, but not html input
var result = md.render('# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$')
ts
import * as mk from 'markdown-it-katex'
import * as MarkdownIt from '@andatoshiki/markdown-it'

const md = new MarkdownIt()
md.use(mk)

// double backslash is not required for TypeScript strings or template literals
const result = md.render('# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$')
import * as mk from 'markdown-it-katex'
import * as MarkdownIt from '@andatoshiki/markdown-it'

const md = new MarkdownIt()
md.use(mk)

// double backslash is not required for TypeScript strings or template literals
const result = md.render('# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$')

3: Configuration ​

The following list of variable are the customizable components of markdown-it-katex, adjust to your needs,

  • katex: You can change KaTeX version by passing the instance.
  • blockClass: Class added to KaTeX block.
  • Apply any other KaTeX options if needed as a regard to the docs
js
md.use(mk, { blockClass: 'math-block', errorColor: ' #cc0000' })
md.use(mk, { blockClass: 'math-block', errorColor: ' #cc0000' })

4: Examples ​

4.1: Inline math ​

To render your LaTeX equations inline, enclose them with a single dollar sign $ on each side of the equation as follows,

tex
$\sqrt{3x-1}+(1+x)^2$
$\sqrt{3x-1}+(1+x)^2$

rendered output equation as follows, 3x−1+(1+x)2\sqrt{3x-1}+(1+x)^2.

4.2: Blocked math ​

To render blocks, use double dollar sign ($$). This mode utilizes larger symbols and centers the result as a block displayed as a <div> block in HTML output, as follows,

tex
$$
\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}
$$
$$
\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}
$$

the above block equation renders the LaTeX equation as a block with output as follows,

∂r∂ωr(yωω)=(yωω){(log⁡y)r+∑i=1r(−1)Ir⋯(r−i+1)(log⁡y)riωi}\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right) = \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}

5: Syntax ​

Math parsing in markdown is designed to comply with the "latex-in-markdown" conventions set by Pandoc,

Anything between two $ characters will be treated as TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit. Thus, $20,000 and $30,000 won’t parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won’t be treated as math delimiters.

  • Pandoc. “Pandoc - Pandoc User’s Guide.” Pandoc.org, pandoc.org/MANUAL.html#math. Accessed 2 Mar. 2023.

6: Supported math syntax ​

KaTeX is a popular, open-source math typesetting library that is based on TeX and LaTeX. It is designed to be easy to use, and to provide high-quality mathematical typesetting for web applications, refer to the following pages of the document for the full list of function support in KaTeX.

Note

Due to the large number of equations rendered on the next following pages, it might takes time to entirely load the webpage, please be patient if the webpage seems to not respond; or it could be a result of slow network connection to correctly render all the equation that causes broken formulas, refresh the page to proceed.