metalsmith-katex

A Metalsmith plugin to render TeX math using KaTeX.

Installation

npm install metalsmith-katex

Usage

TeX formulas can be inserted in a source file between customizable delimiters. The default start and end delimiters are <tex> and </tex>.

Example:

The hypotenuse is computed like this: <tex>c = \sqrt{a^2 + b^2}</tex>.

This plugin supports two options:

• startDelimiter (string): the delimiter to open a new formula.
• endDelimiter (string): the delimiter to close the current formula.

For instance, if you want to delimit your formulas between $s, you can configure this plugin as follows:

CLI

{
  "plugins": {
    "metalsmith-katex": {
      "startDelimiter": "$",
      "endDelimiter": "$"
    }
  }
}

JavaScript:

var katex = require('metalsmith-katex');

metalsmith.use(katex({
  startDelimiter: '$',
  endDelimiter: '$'
}));

Installing the stylesheet and fonts

The HTML generated by KaTeX requires a stylesheet and fonts to render correctly on screen. This plugin does not add them to your project and does not insert <link> elements to your source files.

However, when a file contains mathematical formulas, this plugin will set a flag katex to true in the metadata of that file. You can test this flag in your templates to decide whether to include the stylesheet or not. You can also add this flag manually to the front matter of a file to force the inclusion of the stylesheet. This can be useful if a page contains formulas extracted from another file.

You can download KaTeX from their official website and copy the file katex.min.css to the appropriate location in your project tree.