README

markdown-it-amsmath

A markdown-it plugin for amsmath LaTeX environments.

The following "top-level" environments are parsed, with or without (ending *) numbering: equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.

(these environments are taken from amsmath version 2.1)

Note the split, gathered, aligned, alignedat are not parsed, since they should be used within a parent environment.

See https://executablebooks.github.io/markdown-it-amsmath/ for a demonstration!

Usage

You should "bring your own" math render, provided as an option to the plugin. This function should take the string plus (optional) options, and return a string. For example, below the KaTeX render is used.

As a Node module:

import { renderToString } from "katex"
import MarkdownIt from "markdown-it"
import amsmathPlugin from "markdown-it-amsmath"

const katexOptions = { throwOnError: false, displayMode: true }
const renderer = math => renderToString(math, katexOptions)
const mdit = MarkdownIt().use(amsmathPlugin, { renderer })
const text = mdit.render("\\begin{equation}a = 1\\end{equation}")

In the browser:

<!DOCTYPE html>
<html>
  <head>
    <title>Example Page</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css"
    />
    <script src="https://cdn.jsdelivr.net/npm/markdown-it@12/dist/markdown-it.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js"></script>
    <script src="https://unpkg.com/markdown-it-amsmath"></script>
  </head>
  <body>
    <div id="demo"></div>
    <script>
      const katexOptions = { throwOnError: false, displayMode: true }
      const renderer = math => katex.renderToString(math, katexOptions)
      const mdit = window.markdownit().use(window.markdownitAmsmath, { renderer })
      const text = mdit.render("\\begin{equation}a = 1\\end{equation}")
      document.getElementById("demo").innerHTML = text
    </script>
  </body>
</html>

Development

Features

TypeScript
Code Formatting (prettier)
Code Linting (eslint)
Testing and coverage (jest)
Continuous Integration (GitHub Actions)
Bundled as both UMD and ESM (rollup)
Upload as NPM package and unpkg CDN
Simple demonstration website (GitHub Pages)

Getting Started

Create a GitHub repository from the template.
Replace package details in the following files:
- package.json
- LICENSE
- README.md
- rollup.config.js
Install the node_module dependencies: npm install or npm ci (see Install a project with a clean slate).
Run code formatting; npm run format, and linting: npm run lint:fix.
Run the unit tests; npm test, or with coverage; npm test -- --coverage.

Now you can start to adapt the code in src/index.ts for your plugin, starting with the markdown-it development recommendations.

Modify the test in tests/fixtures.spec.ts, to load your plugin, then the "fixtures" in tests/fixtures, to provide a set of potential Markdown inputs and expected HTML outputs.

On commits/PRs to the master branch, the GH actions will trigger, running the linting, unit tests, and build tests. Additionally setup and uncomment the codecov action in .github/workflows/ci.yml, to provide automated CI coverage.

Finally, you can update the version of your package, e.g.: npm version patch -m "🚀 RELEASE: v%s", push to GitHub; git push --follow-tags, build; npm run build, and publish; npm publish.

Finally, you can adapt the HTML document in docs/, to load both markdown-it and the plugin (from unpkg), then render text from an input area. This can be deployed by GitHub Pages.

Usage no npm install needed!