metalsmith-katex

A Metalsmith plugin to render TeX math using KaTeX.

Current status and alternatives

This module is not maintained and there is no plan to update it. You are free to clone this repository and make any modification that you find appropriate.

If you need KaTeX support in Metalsmith, another option is to use an alternative set of Metalsmith plugins. A working setup is based on the following modules:

• metalsmith-markdownit to use markdown-it as the Markdown processor in Metalsmith.
• markdown-it-math, a markdown-it plugin to include math in Markdown.
• katex as the math rendering backend for markdown-it-math.

Here is an example build.js:

var markdown = require("metalsmith-markdownit");
var math = require("markdown-it-math");
var katex = require("katex");

var md = markdown("commonmark", { /* your options */ });
md.parser.use(math, {
    inlineRenderer: str => katex.renderToString(str),
    blockRenderer: str => katex.renderToString(str, {displayMode: true});
});

Metalsmith(__dirname)
    .use(md)
    .build(err => {
        if (err) throw err;
    });

If you still want to use metalsmith-katex, follow the instructions below:

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 the following options:

• startDelimiter (string): the delimiter to open a new formula.
• endDelimiter (string): the delimiter to close the current formula.
• Other options are passed to KaTeX.

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. You can also install it using bower:

bower install katex