rehype-katex

What is rehype-katex?

The rehype-katex package is a plugin for the rehype ecosystem that allows you to transform LaTeX math expressions into HTML using KaTeX. This is particularly useful for rendering mathematical content in web pages.

What are rehype-katex's main functionalities?

Basic LaTeX to HTML Conversion

This feature allows you to convert LaTeX math expressions within your HTML content into properly formatted HTML using KaTeX. The code sample demonstrates how to use rehype-katex to process a string containing a LaTeX expression.

const rehype = require('rehype');
const rehypeKatex = require('rehype-katex');

const html = rehype()
  .use(rehypeKatex)
  .processSync('Here is some math: $E = mc^2$')
  .toString();

console.log(html);

Custom KaTeX Options

This feature allows you to customize the behavior of KaTeX by passing options. In the code sample, the `throwOnError` option is set to `false` to prevent errors from being thrown, and `errorColor` is set to customize the color of error messages.

const rehype = require('rehype');
const rehypeKatex = require('rehype-katex');

const html = rehype()
  .use(rehypeKatex, { throwOnError: false, errorColor: '#cc0000' })
  .processSync('Here is some math: $E = mc^2$')
  .toString();

console.log(html);

Other packages similar to rehype-katex

remark-math

remark-math is a plugin for the remark ecosystem that parses and renders LaTeX math expressions in Markdown. It is similar to rehype-katex but is used within the remark ecosystem for Markdown processing.

markdown-it-katex

markdown-it-katex is a plugin for the markdown-it Markdown parser that allows you to render LaTeX math expressions within Markdown content. It is similar to rehype-katex but is used within the markdown-it ecosystem.

gatsby-remark-katex

gatsby-remark-katex is a plugin for Gatsby that allows you to render LaTeX math expressions in Markdown files. It is similar to rehype-katex but is specifically designed for use with Gatsby.

README

rehype-katex

rehype plugin to render <span class=math-inline> and <div class=math-display> with KaTeX.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(rehypeKatex[, options])
• CSS
• Syntax tree
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (rehype) plugin to render math. You can combine it with remark-math for math in markdown or add math-inline and math-display classes in HTML.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that transforms hast.

When should I use this?

This project is useful as it renders math with KaTeX at compile time, which means that there is no client side JavaScript needed.

A different plugin, rehype-mathjax, is similar but uses MathJax instead.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install rehype-katex

In Deno with Skypack:

import rehypeKatex from 'https://cdn.skypack.dev/rehype-katex@6?dts'

In browsers with Skypack:

<script type="module">
  import rehypeKatex from 'https://cdn.skypack.dev/rehype-katex@6?min'
</script>

Use

Say we have the following file example.html:

<p>
  Lift(<span class="math math-inline">L</span>) can be determined by Lift Coefficient
  (<span class="math math-inline">C_L</span>) like the following equation.
</p>

<div class="math math-display">
  L = \frac{1}{2} \rho v^2 S C_L
</div>

And our module example.js looks as follows:

import {read} from 'to-vfile'
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeKatex from 'rehype-katex'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'

main()

async function main() {
  const file = await unified()
    .use(rehypeParse, {fragment: true})
    .use(rehypeKatex)
    .use(rehypeDocument, {
      css: 'https://cdn.jsdelivr.net/npm/katex@0.15.0/dist/katex.min.css'
    })
    .use(rehypeStringify)
    .process(await read('example.html'))

  console.log(String(file))
}

Now running node example.js yields:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>example</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.0/dist/katex.min.css">
</head>
<body>
<p>
  Lift(<span class="math math-inline"><span class="katex">…</span></span>) can be determined by Lift Coefficient
  (<span class="math math-inline"><span class="katex">…</span></span>) like the following equation.
</p>
<div class="math math-display"><span class="katex-display">…</span></div>
</body>
</html>

API

This package exports no identifiers. The default export is rehypeKatex.

unified().use(rehypeKatex[, options])

Transform <span class="math-inline"> and <div class="math-display"> with KaTeX.

options

Configuration (optional). All options, except for displayMode, are passed to KaTeX.

options.throwOnError

Throw if a KaTeX parse error occurs (boolean, default: false). See KaTeX options.

CSS

The HTML produced by KaTeX requires CSS to render correctly. You should use katex.css somewhere on the page where the math is shown to style it properly. At the time of writing, the last version is:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.0/dist/katex.min.css" integrity="sha384-RZU/ijkSsFbcmivfdRBQDtwuwVqK7GMOw6IMvKyeWL2K5UAlyp6WonmB8m7Jd0Hn" crossorigin="anonymous">

Syntax tree

This plugin transforms elements with a class name of either math-inline and/or math-display.

Types

This package is fully typed with TypeScript. An extra Options type is exported, which models the accepted options.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified version 6+ and rehype version 4+.

Security

Using rehype-katex should be safe assuming that you trust KaTeX. Any vulnerability in it could open you to a cross-site scripting (XSS) attack. Always be wary of user input and use rehype-sanitize.

When you don’t trust user content but do trust KaTeX, you can allow the classes added by remark-math while disallowing anything else in the rehype-sanitize schema, and run rehype-katex afterwards. Like so:

import rehypeSanitize, {defaultSchema} from 'rehype-stringify'

const mathSanitizeSchema = {
  ...defaultSchema,
  attributes: {
    ...defaultSchema.attributes,
    div: [
      ...defaultSchema.attributes.div,
      ['className', 'math', 'math-display']
    ],
    span: [
      ['className', 'math', 'math-inline']
    ]
  }
}

// …

unified()
  // …
  .use(rehypeSanitize, mathSanitizeSchema)
  .use(rehypeKatex)
  // …

Related

• rehype-mathjax — same but with MathJax
• rehype-highlight — highlight code blocks
• rehype-autolink-headings — add links to headings
• rehype-sanitize — sanitize HTML
• rehype-document — wrap a document around the tree

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Junyoung Choi